@abraca/dabra 1.8.1 → 1.9.1

package/src/TreeManager.ts

@@ -0,0 +1,429 @@
+/**
+ * TreeManager — typed ORM layer over the root Y.Doc's "doc-tree" / "doc-trash"
+ * Y.Maps.
+ *
+ * Extracted from `mcp/tools/tree.ts` and `cli/commands/documents.ts` logic.
+ * All tree CRUD operations go through this class.
+ */
+import * as Y from "yjs";
+import type {
+	TreeEntry,
+	TreeNode,
+	TreeSearchResult,
+	PageMeta,
+} from "./DocTypes.ts";
+import { toPlain, normalizeRootId } from "./DocUtils.ts";
+import type { DocumentManager } from "./DocumentManager.ts";
+
+export class TreeManager {
+	constructor(private dm: DocumentManager) {}
+
+	// ── Reading ───────────────────────────────────────────────────────────────
+
+	/** Read all tree entries as plain objects. */
+	readEntries(): TreeEntry[] {
+		const treeMap = this.dm.getTreeMap();
+		if (!treeMap) return [];
+
+		const entries: TreeEntry[] = [];
+		treeMap.forEach((raw: unknown, id: string) => {
+			const value = toPlain(raw) as Record<string, unknown>;
+			if (typeof value !== "object" || value === null) return;
+			entries.push({
+				id,
+				label: (value.label as string) || "Untitled",
+				parentId: (value.parentId as string | null) ?? null,
+				order: (value.order as number) ?? 0,
+				type: value.type as string | undefined,
+				meta: value.meta as PageMeta | undefined,
+				createdAt: value.createdAt as number | undefined,
+				updatedAt: value.updatedAt as number | undefined,
+			});
+		});
+		return entries;
+	}
+
+	/** Get immediate children of a parent (sorted by order). */
+	childrenOf(parentId: string | null): TreeEntry[] {
+		const normalized = normalizeRootId(parentId, this.dm.rootDocId);
+		return this.readEntries()
+			.filter((e) => e.parentId === normalized)
+			.sort((a, b) => (a.order ?? 0) - (b.order ?? 0));
+	}
+
+	/** Get all descendants recursively. */
+	descendantsOf(parentId: string | null): TreeEntry[] {
+		const normalized = normalizeRootId(parentId, this.dm.rootDocId);
+		const entries = this.readEntries();
+		const result: TreeEntry[] = [];
+		const visited = new Set<string>();
+
+		const collect = (pid: string | null) => {
+			if (pid !== null && visited.has(pid)) return;
+			if (pid !== null) visited.add(pid);
+			for (const child of entries
+				.filter((e) => e.parentId === pid)
+				.sort((a, b) => (a.order ?? 0) - (b.order ?? 0))) {
+				result.push(child);
+				collect(child.id);
+			}
+		};
+		collect(normalized);
+		return result;
+	}
+
+	/** Build nested tree JSON. */
+	buildTree(
+		rootId?: string | null,
+		maxDepth = 3,
+	): TreeNode[] {
+		const normalized = normalizeRootId(
+			rootId ?? null,
+			this.dm.rootDocId,
+		);
+		const entries = this.readEntries();
+		return this._buildTree(entries, normalized, maxDepth, 0, new Set());
+	}
+
+	private _buildTree(
+		entries: TreeEntry[],
+		rootId: string | null,
+		maxDepth: number,
+		currentDepth: number,
+		visited: Set<string>,
+	): TreeNode[] {
+		if (maxDepth >= 0 && currentDepth >= maxDepth) return [];
+		const children = entries
+			.filter((e) => e.parentId === rootId)
+			.sort((a, b) => (a.order ?? 0) - (b.order ?? 0));
+
+		return children
+			.filter((e) => !visited.has(e.id))
+			.map((entry) => {
+				const next = new Set(visited);
+				next.add(entry.id);
+				return {
+					id: entry.id,
+					label: entry.label,
+					type: entry.type,
+					meta: entry.meta,
+					order: entry.order,
+					children: this._buildTree(
+						entries,
+						entry.id,
+						maxDepth,
+						currentDepth + 1,
+						next,
+					),
+				};
+			});
+	}
+
+	/** Find a single entry by ID. */
+	get(docId: string): TreeEntry | null {
+		const treeMap = this.dm.getTreeMap();
+		if (!treeMap) return null;
+		const raw = treeMap.get(docId);
+		if (!raw) return null;
+		const value = toPlain(raw) as Record<string, unknown>;
+		if (typeof value !== "object" || value === null) return null;
+		return {
+			id: docId,
+			label: (value.label as string) || "Untitled",
+			parentId: (value.parentId as string | null) ?? null,
+			order: (value.order as number) ?? 0,
+			type: value.type as string | undefined,
+			meta: value.meta as PageMeta | undefined,
+			createdAt: value.createdAt as number | undefined,
+			updatedAt: value.updatedAt as number | undefined,
+		};
+	}
+
+	/** Search by label (case-insensitive substring match). */
+	find(
+		query: string,
+		rootId?: string | null,
+	): TreeSearchResult[] {
+		const entries = this.readEntries();
+		const lowerQuery = query.toLowerCase();
+
+		const normalized = normalizeRootId(
+			rootId ?? null,
+			this.dm.rootDocId,
+		);
+		const searchSet = normalized
+			? this.descendantsOf(normalized)
+			: entries;
+
+		const matches = searchSet.filter((e) =>
+			e.label.toLowerCase().includes(lowerQuery),
+		);
+
+		const byId = new Map(entries.map((e) => [e.id, e]));
+		return matches.map((entry) => {
+			const path: string[] = [];
+			let current = entry.parentId;
+			const visited = new Set<string>();
+			while (current && !visited.has(current)) {
+				visited.add(current);
+				const parent = byId.get(current);
+				if (!parent) break;
+				path.unshift(parent.label);
+				current = parent.parentId;
+			}
+			return {
+				id: entry.id,
+				label: entry.label,
+				type: entry.type,
+				meta: entry.meta,
+				path,
+			};
+		});
+	}
+
+	// ── Writing ──────────────────────────────────────────────────────────────
+
+	/** Create a new document in the tree. Returns the new entry. */
+	create(opts: {
+		parentId?: string | null;
+		label: string;
+		type?: string;
+		meta?: Partial<PageMeta>;
+	}): TreeEntry {
+		const treeMap = this.dm.getTreeMap();
+		const rootDoc = this.dm.rootDocument;
+		if (!treeMap || !rootDoc) {
+			throw new Error("Not connected");
+		}
+
+		const id = crypto.randomUUID();
+		const normalizedParent = normalizeRootId(
+			opts.parentId ?? null,
+			this.dm.rootDocId,
+		);
+		const now = Date.now();
+
+		rootDoc.transact(() => {
+			treeMap.set(id, {
+				label: opts.label,
+				parentId: normalizedParent,
+				order: now,
+				type: opts.type,
+				meta: opts.meta as PageMeta,
+				createdAt: now,
+				updatedAt: now,
+			});
+		});
+
+		return {
+			id,
+			label: opts.label,
+			parentId: normalizedParent,
+			order: now,
+			type: opts.type,
+			meta: opts.meta as PageMeta | undefined,
+			createdAt: now,
+			updatedAt: now,
+		};
+	}
+
+	/** Rename a document. */
+	rename(docId: string, label: string): void {
+		const treeMap = this.dm.getTreeMap();
+		if (!treeMap) throw new Error("Not connected");
+
+		const raw = treeMap.get(docId);
+		if (!raw) throw new Error(`Document ${docId} not found`);
+
+		const entry = toPlain(raw) as Record<string, unknown>;
+		treeMap.set(docId, { ...entry, label, updatedAt: Date.now() });
+	}
+
+	/** Move a document to a new parent. */
+	move(
+		docId: string,
+		newParentId?: string | null,
+		order?: number,
+	): void {
+		const treeMap = this.dm.getTreeMap();
+		if (!treeMap) throw new Error("Not connected");
+
+		const raw = treeMap.get(docId);
+		if (!raw) throw new Error(`Document ${docId} not found`);
+
+		const entry = toPlain(raw) as Record<string, unknown>;
+		treeMap.set(docId, {
+			...entry,
+			parentId: normalizeRootId(
+				newParentId ?? null,
+				this.dm.rootDocId,
+			),
+			order: order ?? Date.now(),
+			updatedAt: Date.now(),
+		});
+	}
+
+	/** Change the page type of a document. */
+	changeType(docId: string, type: string): void {
+		const treeMap = this.dm.getTreeMap();
+		if (!treeMap) throw new Error("Not connected");
+
+		const raw = treeMap.get(docId);
+		if (!raw) throw new Error(`Document ${docId} not found`);
+
+		const entry = toPlain(raw) as Record<string, unknown>;
+		treeMap.set(docId, { ...entry, type, updatedAt: Date.now() });
+	}
+
+	/**
+	 * Soft-delete a document and descendants (move to trash).
+	 * @returns count of deleted documents
+	 */
+	delete(docId: string): number {
+		const treeMap = this.dm.getTreeMap();
+		const trashMap = this.dm.getTrashMap();
+		const rootDoc = this.dm.rootDocument;
+		if (!treeMap || !trashMap || !rootDoc) {
+			throw new Error("Not connected");
+		}
+
+		const entries = this.readEntries();
+		const toDelete = [
+			docId,
+			...this._descendantIds(entries, docId),
+		];
+
+		const now = Date.now();
+		rootDoc.transact(() => {
+			for (const nid of toDelete) {
+				const raw = treeMap.get(nid);
+				if (!raw) continue;
+				const entry = toPlain(raw) as Record<string, unknown>;
+				trashMap.set(nid, {
+					label: entry.label || "Untitled",
+					parentId: entry.parentId ?? null,
+					order: entry.order ?? 0,
+					type: entry.type,
+					meta: entry.meta,
+					deletedAt: now,
+				});
+				treeMap.delete(nid);
+			}
+		});
+
+		return toDelete.length;
+	}
+
+	/** Duplicate a document (shallow clone). Returns the new entry. */
+	duplicate(docId: string): TreeEntry {
+		const treeMap = this.dm.getTreeMap();
+		if (!treeMap) throw new Error("Not connected");
+
+		const raw = treeMap.get(docId);
+		if (!raw) throw new Error(`Document ${docId} not found`);
+
+		const entry = toPlain(raw) as Record<string, unknown>;
+		const newId = crypto.randomUUID();
+		const now = Date.now();
+		treeMap.set(newId, {
+			...entry,
+			label: ((entry.label as string) || "Untitled") + " (copy)",
+			order: now,
+		});
+
+		return {
+			id: newId,
+			label: ((entry.label as string) || "Untitled") + " (copy)",
+			parentId: (entry.parentId as string | null) ?? null,
+			order: now,
+			type: entry.type as string | undefined,
+			meta: entry.meta as PageMeta | undefined,
+			createdAt: entry.createdAt as number | undefined,
+			updatedAt: entry.updatedAt as number | undefined,
+		};
+	}
+
+	/** Restore a document from trash back into the tree. */
+	restore(docId: string): void {
+		const treeMap = this.dm.getTreeMap();
+		const trashMap = this.dm.getTrashMap();
+		const rootDoc = this.dm.rootDocument;
+		if (!treeMap || !trashMap || !rootDoc) {
+			throw new Error("Not connected");
+		}
+
+		const raw = trashMap.get(docId);
+		if (!raw) throw new Error(`Document ${docId} not found in trash`);
+
+		const entry = toPlain(raw) as Record<string, unknown>;
+		const now = Date.now();
+		rootDoc.transact(() => {
+			treeMap.set(docId, {
+				label: entry.label || "Untitled",
+				parentId: entry.parentId ?? null,
+				order: entry.order ?? now,
+				type: entry.type,
+				meta: entry.meta,
+				createdAt: entry.createdAt ?? now,
+				updatedAt: now,
+			});
+			trashMap.delete(docId);
+		});
+	}
+
+	/** List trashed documents. */
+	listTrash(): TreeEntry[] {
+		const trashMap = this.dm.getTrashMap();
+		if (!trashMap) return [];
+
+		const entries: TreeEntry[] = [];
+		trashMap.forEach((raw: unknown, id: string) => {
+			const value = toPlain(raw) as Record<string, unknown>;
+			if (typeof value !== "object" || value === null) return;
+			entries.push({
+				id,
+				label: (value.label as string) || "Untitled",
+				parentId: (value.parentId as string | null) ?? null,
+				order: (value.order as number) ?? 0,
+				type: value.type as string | undefined,
+				meta: value.meta as PageMeta | undefined,
+			});
+		});
+		return entries;
+	}
+
+	/** Get enabled plugin names from space-plugins map. */
+	getEnabledPlugins(): string[] {
+		const pluginsMap = this.dm.getPluginsMap();
+		if (!pluginsMap) return [];
+
+		const plugins: string[] = [];
+		pluginsMap.forEach((raw: unknown, key: string) => {
+			const value = toPlain(raw) as Record<string, unknown>;
+			if (value && value.enabled) {
+				plugins.push(key);
+			}
+		});
+		return plugins;
+	}
+
+	// ── Internal helpers ──────────────────────────────────────────────────────
+
+	private _descendantIds(
+		entries: TreeEntry[],
+		parentId: string,
+	): string[] {
+		const result: string[] = [];
+		const visited = new Set<string>();
+		const collect = (pid: string) => {
+			if (visited.has(pid)) return;
+			visited.add(pid);
+			for (const child of entries.filter((e) => e.parentId === pid)) {
+				result.push(child.id);
+				collect(child.id);
+			}
+		};
+		collect(parentId);
+		return result;
+	}
+}

package/src/types.ts

@@ -124,10 +124,19 @@ export type onStatelessParameters = {
   payload: string;
 };
 
+/** Fired by E2EAbracadabraProvider when the server acknowledges an E2E
+ * client-side compaction (via the `snapshot:compacted` stateless broadcast). */
+export type onCompactedParameters = {
+  docId: string;
+  /** User id that performed the compaction; undefined if payload was malformed. */
+  by: string | undefined;
+};
+
 export type onServerErrorParameters = {
   source: string;
   code: string;
   message: string;
+  meta?: Record<string, unknown>;
 };
 
 export type StatesArray = { clientId: number; [key: string | number]: any }[];