@abraca/mcp 2.8.0 → 2.10.0

package/src/tools/tree.ts

@@ -25,9 +25,22 @@ function toPlain(val: any): any {
   return val instanceof Y.Map ? val.toJSON() : val
 }
 
-function readEntries(treeMap: Y.Map<any>): TreeEntry[] {
+/**
+ * Read every doc-tree entry, optionally skipping the space's self-descriptor.
+ *
+ * A space's own `doc-tree` Y.Map holds an entry keyed by the space's OWN id
+ * (the connected root doc), with `parentId: null` and `order: -1`. It stores
+ * the space root's own icon/color/type/label — it is NOT a child document.
+ * Because its `parentId` is null it otherwise shows up alongside real
+ * top-level docs, making the space render as a phantom first child of itself
+ * ("Health space's first document is 'Development'"). Pass `selfId =
+ * server.rootDocId` to drop it. cou-sh's DocumentTree applies the same guard
+ * (`if (id === spaceDocId) continue`).
+ */
+export function readEntries(treeMap: Y.Map<any>, selfId?: string | null): TreeEntry[] {
   const entries: TreeEntry[] = []
   treeMap.forEach((raw: any, id: string) => {
+    if (selfId && id === selfId) return // skip the space root's self-descriptor entry
     const value = toPlain(raw)
     if (typeof value !== 'object' || value === null) return // skip non-entry keys (e.g. ":updatedAt" timestamps)
     entries.push({
@@ -65,7 +78,7 @@ function descendantsOf(entries: TreeEntry[], id: string | null): TreeEntry[] {
   return result
 }
 
-function buildTree(entries: TreeEntry[], rootId: string | null, maxDepth: number, currentDepth = 0, visited = new Set<string>()): any[] {
+export function buildTree(entries: TreeEntry[], rootId: string | null, maxDepth: number, currentDepth = 0, visited = new Set<string>()): any[] {
   if (maxDepth >= 0 && currentDepth >= maxDepth) return []
   const children = childrenOf(entries, rootId)
   return children.filter(e => !visited.has(e.id)).map(entry => {
@@ -94,13 +107,14 @@ export function registerTreeTools(
     async ({ parentId }) => {
       server.setAutoStatus('reading')
       server.setActiveToolCall({ name: 'list_documents' })
+      await server.ensureSpaceActive(parentId)
       const treeMap = server.getTreeMap()
       if (!treeMap) {
         return { content: [{ type: 'text', text: 'Not connected' }] }
       }
 
       const targetId = normalizeRootId(parentId, server)
-      const entries = readEntries(treeMap)
+      const entries = readEntries(treeMap, server.rootDocId)
       const children = childrenOf(entries, targetId)
 
       return {
@@ -122,6 +136,7 @@ export function registerTreeTools(
     async ({ rootId, depth }) => {
       server.setAutoStatus('reading')
       server.setActiveToolCall({ name: 'get_document_tree' })
+      await server.ensureSpaceActive(rootId)
       const treeMap = server.getTreeMap()
       if (!treeMap) {
         return { content: [{ type: 'text', text: 'Not connected' }] }
@@ -129,7 +144,7 @@ export function registerTreeTools(
 
       const targetId = normalizeRootId(rootId, server)
       const maxDepth = depth ?? 3
-      const entries = readEntries(treeMap)
+      const entries = readEntries(treeMap, server.rootDocId)
       const tree = buildTree(entries, targetId, maxDepth)
 
       return {
@@ -151,12 +166,13 @@ export function registerTreeTools(
     async ({ query, rootId }) => {
       server.setAutoStatus('searching')
       server.setActiveToolCall({ name: 'find_document', target: query })
+      await server.ensureSpaceActive(rootId)
       const treeMap = server.getTreeMap()
       if (!treeMap) {
         return { content: [{ type: 'text', text: 'Not connected' }] }
       }
 
-      const entries = readEntries(treeMap)
+      const entries = readEntries(treeMap, server.rootDocId)
       const lowerQuery = query.toLowerCase()
 
       // If rootId specified, restrict to descendants only
@@ -261,6 +277,11 @@ export function registerTreeTools(
       server.setAutoStatus('creating')
       server.setActiveToolCall({ name: 'create_document', target: label })
 
+      // Activate the space that owns `parentId` first, so the new doc lands in
+      // the right space's tree instead of being orphaned into whatever space
+      // happened to be active (the silent data-loss path).
+      await server.ensureSpaceActive(parentId)
+
       const treeMap = server.getTreeMap()
       const rootDoc = server.rootDocument
       if (!treeMap || !rootDoc) {
@@ -284,6 +305,48 @@ export function registerTreeTools(
       const id = crypto.randomUUID()
       const normalizedParent = normalizeRootId(parentId, server)
       const now = Date.now()
+
+      // Guard: never write under a parent that doesn't exist in the resolved
+      // space's tree — that silently orphans the doc (it would be invisible in
+      // the intended space forever). Refuse with actionable guidance instead.
+      if (normalizedParent && !treeMap.has(normalizedParent)) {
+        return {
+          content: [{
+            type: 'text',
+            text: `Parent "${parentId}" was not found in any space the MCP can currently reach (active space: ${server.rootDocId}). Refusing to create — writing here would orphan the document. If the parent lives in another space, call switch_space to that space first, then retry.`,
+          }],
+          isError: true,
+        }
+      }
+
+      // Register the SQL `documents` row BEFORE writing the Yjs tree entry.
+      // The RBAC cascade seeds from `documents WHERE id=?`, so a doc with no
+      // row can't walk up to inherit its parent's permissions — it falls to
+      // the flat `[access].authenticated` floor and is missing from
+      // `GET /docs` + FTS. `createChild` registers the row under the right
+      // parent (the current space root when no explicit parent is given) so
+      // permissions inherit. Doing it first means a failure here doesn't leave
+      // a permission-orphaned Yjs ghost.
+      const restParent = normalizedParent ?? server.rootDocId
+      if (restParent) {
+        try {
+          await server.client.createChild(restParent, {
+            child_id: id,
+            label,
+            doc_type: type,
+            kind: 'page',
+          })
+        } catch (e) {
+          return {
+            content: [{
+              type: 'text',
+              text: `Failed to register document ${id} under ${restParent}: ${e instanceof Error ? e.message : String(e)}`,
+            }],
+            isError: true,
+          }
+        }
+      }
+
       rootDoc.transact(() => {
         treeMap.set(
           id,
@@ -320,6 +383,7 @@ export function registerTreeTools(
     async ({ id, label }) => {
       server.setAutoStatus('writing')
       server.setActiveToolCall({ name: 'rename_document', target: id })
+      await server.ensureSpaceActive(id)
       const treeMap = server.getTreeMap()
       if (!treeMap) {
         return { content: [{ type: 'text', text: 'Not connected' }] }
@@ -331,7 +395,21 @@ export function registerTreeTools(
       }
 
       patchEntry(treeMap, id, { label, updatedAt: Date.now() })
-      return { content: [{ type: 'text', text: `Renamed to "${label}"` }] }
+      // Keep the SQL `documents.label` registry in step with the Yjs label so
+      // `list_spaces` / `GET /docs` / FTS reflect the rename. Critical for
+      // SPACE docs: the server-side label reconcile deliberately skips
+      // `kind='space'` rows (their name is REST-canonical) and cou-sh renders
+      // the registry name for space roots — so without this a renamed space
+      // would keep its old name everywhere but the Yjs self-entry (the exact
+      // "Health shows as Development" bug). Best-effort: a purely-Yjs (no-row)
+      // doc PATCHes to a harmless no-op.
+      let restNote = ''
+      try {
+        await server.client.updateDocumentMeta(id, { label })
+      } catch (e) {
+        restNote = ` (registry update failed: ${e instanceof Error ? e.message : String(e)})`
+      }
+      return { content: [{ type: 'text', text: `Renamed to "${label}"${restNote}` }] }
     }
   )
 
@@ -346,6 +424,7 @@ export function registerTreeTools(
     async ({ id, newParentId, order }) => {
       server.setAutoStatus('writing')
       server.setActiveToolCall({ name: 'move_document', target: id })
+      await server.ensureSpaceActive(id)
       const treeMap = server.getTreeMap()
       if (!treeMap) {
         return { content: [{ type: 'text', text: 'Not connected' }] }
@@ -356,12 +435,41 @@ export function registerTreeTools(
         return { content: [{ type: 'text', text: `Document ${id} not found` }] }
       }
 
+      const normalizedParent = normalizeRootId(newParentId, server)
+      // Cross-space moves aren't supported through a single tree map: the new
+      // parent must live in the same space as the doc being moved. Refuse
+      // rather than reparent onto a non-node (which would orphan the doc).
+      if (normalizedParent && !treeMap.has(normalizedParent)) {
+        return {
+          content: [{
+            type: 'text',
+            text: `New parent "${newParentId}" is not in the same space as "${id}" (active space: ${server.rootDocId}). Cross-space moves aren't supported — refusing to avoid orphaning the document.`,
+          }],
+          isError: true,
+        }
+      }
       patchEntry(treeMap, id, {
-        parentId: normalizeRootId(newParentId, server),
+        parentId: normalizedParent,
         order: order ?? Date.now(),
         updatedAt: Date.now(),
       })
-      return { content: [{ type: 'text', text: `Moved ${id} to parent ${newParentId}` }] }
+      // Mirror the reparent into the SQL `documents` row via the
+      // permission-checked REST path. The RBAC cascade walks `documents.parent_id`,
+      // so a Yjs-only move would leave permission resolution on the OLD ancestry.
+      // PATCH enforces manage-on-new-parent + cycle checks server-side (we never
+      // project Yjs parentId straight to SQL — that would be an escalation hole).
+      // REST parent for "top level" is the current space root. No-op for a
+      // purely-Yjs (no-row) doc.
+      const restParent = normalizedParent ?? server.rootDocId
+      let restNote = ''
+      if (restParent) {
+        try {
+          await server.client.updateDocumentMeta(id, { parent_id: restParent })
+        } catch (e) {
+          restNote = ` (registry reparent failed: ${e instanceof Error ? e.message : String(e)})`
+        }
+      }
+      return { content: [{ type: 'text', text: `Moved ${id} to parent ${newParentId}${restNote}` }] }
     }
   )
 
@@ -374,6 +482,7 @@ export function registerTreeTools(
     async ({ id }) => {
       server.setAutoStatus('writing')
       server.setActiveToolCall({ name: 'delete_document', target: id })
+      await server.ensureSpaceActive(id)
       const treeMap = server.getTreeMap()
       const trashMap = server.getTrashMap()
       const rootDoc = server.rootDocument
@@ -381,7 +490,7 @@ export function registerTreeTools(
         return { content: [{ type: 'text', text: 'Not connected' }] }
       }
 
-      const entries = readEntries(treeMap)
+      const entries = readEntries(treeMap, server.rootDocId)
       const toDelete = [id, ...descendantsOf(entries, id).map(e => e.id)]
 
       const now = Date.now()
@@ -402,7 +511,17 @@ export function registerTreeTools(
         }
       })
 
-      return { content: [{ type: 'text', text: `Deleted ${toDelete.length} document(s)` }] }
+      // Soft-delete the SQL `documents` row too (server cascades to descendants),
+      // else the row stays live and the doc keeps showing up in `GET /docs` + FTS
+      // search while hidden from the tree. Best-effort; no-op for a no-row doc.
+      let restNote = ''
+      try {
+        await server.client.deleteDoc(id)
+      } catch (e) {
+        restNote = ` (registry delete failed: ${e instanceof Error ? e.message : String(e)})`
+      }
+
+      return { content: [{ type: 'text', text: `Deleted ${toDelete.length} document(s)${restNote}` }] }
     }
   )
 
@@ -416,6 +535,7 @@ export function registerTreeTools(
     async ({ id, type }) => {
       server.setAutoStatus('writing')
       server.setActiveToolCall({ name: 'change_document_type', target: id })
+      await server.ensureSpaceActive(id)
       const treeMap = server.getTreeMap()
       if (!treeMap) {
         return { content: [{ type: 'text', text: 'Not connected' }] }
@@ -436,6 +556,7 @@ export function registerTreeTools(
     'List all Spaces available on the server. Spaces are top-level documents (direct children of the server root) tagged with kind="space". Returns id, label, public_access, and active flag. Use switch_space to navigate.',
     {},
     async () => {
+      server.setActiveToolCall({ name: 'list_spaces' })
       const spaces = server.spaces
       if (!spaces.length) {
         return { content: [{ type: 'text', text: 'No spaces available — create one to get started.' }] }
@@ -451,6 +572,7 @@ export function registerTreeTools(
     'Switch the active Space. All subsequent tree operations will target the new Space. Use list_spaces to discover available ids.',
     { docId: z.string().describe('The id of the Space to switch to (from list_spaces).') },
     async ({ docId }) => {
+      server.setActiveToolCall({ name: 'switch_space', target: docId })
       await server.switchSpace(docId)
       const space = server.spaces.find(s => s.id === docId)
       const name = space?.label ?? docId
@@ -465,6 +587,8 @@ export function registerTreeTools(
       id: z.string().describe('Document ID to duplicate.'),
     },
     async ({ id }) => {
+      server.setActiveToolCall({ name: 'duplicate_document', target: id })
+      await server.ensureSpaceActive(id)
       const treeMap = server.getTreeMap()
       if (!treeMap) return { content: [{ type: 'text', text: 'Not connected' }] }
 
@@ -500,6 +624,7 @@ export function registerTreeTools(
       key: z.string().optional().describe('Filter to a single type by key (e.g. "kanban", "calendar"). Aliases are resolved (e.g. "desktop" → "dashboard"). Omit to list all types.'),
     },
     async ({ key }) => {
+      server.setActiveToolCall({ name: 'list_page_types', target: key })
       if (key) {
         const resolved = resolvePageType(key)
         if (!resolved) {

package/src/utils.ts

@@ -1,10 +1,24 @@
 /**
  * Wait for a provider's `synced` event with a timeout.
+ *
+ * Mirrors `@abraca/dabra`'s `DocUtils.waitForSync`: the `isSynced` short-circuit
+ * is load-bearing. `synced` is emitted once per sync transition (and deferred a
+ * microtask), so a provider that has ALREADY synced — e.g. the cached child
+ * provider that `loadChild` returns on a repeat read/write of the same doc —
+ * will never re-emit. Without this guard those callers block for the full
+ * `timeoutMs` ("works once, then every later op on that doc times out at 15s").
  */
 export function waitForSync(
-  provider: { on(event: string, cb: () => void): void; off(event: string, cb: () => void): void },
+  provider: {
+    isSynced?: boolean
+    on(event: string, cb: () => void): void
+    off(event: string, cb: () => void): void
+  },
   timeoutMs = 15000
 ): Promise<void> {
+  // Already synced — resolve immediately (no event will fire again).
+  if (provider.isSynced) return Promise.resolve()
+
   return new Promise<void>((resolve, reject) => {
     const timer = setTimeout(() => {
       provider.off('synced', handler)
@@ -13,6 +27,7 @@ export function waitForSync(
 
     function handler() {
       clearTimeout(timer)
+      provider.off('synced', handler)
       resolve()
     }