@abraca/dabra 1.8.2 → 2.0.0

package/src/TreeManager.ts

@@ -0,0 +1,473 @@
+/**
+ * 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 { resolvePageType } 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,
+		};
+	}
+
+	/**
+	 * Create a document and auto-apply renderer defaults from the page type's
+	 * `defaultMetaFields` (toggle fields with `default` values).
+	 */
+	createWithTypeDefaults(opts: {
+		parentId?: string | null;
+		label: string;
+		type: string;
+		extraMeta?: Partial<PageMeta>;
+	}): TreeEntry {
+		const typeInfo = resolvePageType(opts.type);
+		const autoMeta: Record<string, unknown> = {};
+		if (typeInfo?.defaultMetaFields) {
+			for (const field of typeInfo.defaultMetaFields) {
+				if (field.type === "toggle" && field.key && field.default !== undefined) {
+					autoMeta[field.key] = field.default;
+				}
+			}
+		}
+		const mergedMeta =
+			Object.keys(autoMeta).length > 0 || opts.extraMeta
+				? { ...autoMeta, ...(opts.extraMeta ?? {}) }
+				: undefined;
+		return this.create({
+			parentId: opts.parentId,
+			label: opts.label,
+			type: opts.type,
+			meta: mergedMeta,
+		});
+	}
+
+	/** Rename a document. */
+	rename(docId: string, label: string): void {
+		const treeMap = this.dm.getTreeMap();
+		const rootDoc = this.dm.rootDocument;
+		if (!treeMap || !rootDoc) 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>;
+		rootDoc.transact(() => {
+			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();
+		const rootDoc = this.dm.rootDocument;
+		if (!treeMap || !rootDoc) 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>;
+		rootDoc.transact(() => {
+			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();
+		const rootDoc = this.dm.rootDocument;
+		if (!treeMap || !rootDoc) 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>;
+		rootDoc.transact(() => {
+			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();
+		const newLabel = ((entry.label as string) || "Untitled") + " (copy)";
+		treeMap.set(newId, {
+			...entry,
+			label: newLabel,
+			order: now,
+			createdAt: now,
+			updatedAt: now,
+		});
+
+		return {
+			id: newId,
+			label: newLabel,
+			parentId: (entry.parentId as string | null) ?? null,
+			order: now,
+			type: entry.type as string | undefined,
+			meta: entry.meta as PageMeta | undefined,
+			createdAt: now,
+			updatedAt: now,
+		};
+	}
+
+	/** 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/TreeTimestamps.ts

@@ -8,8 +8,9 @@
  * This propagates "last edited" timestamps to all peers via the root CRDT,
  * without requiring any server-side changes.
  *
- * A trailing-edge throttle (default 5 s) limits writes to avoid CRDT bloat
- * on the root doc during rapid typing.
+ * Leading-edge + trailing-edge throttle (default 5 s window): the first
+ * update flushes immediately so the "last edited" badge updates instantly;
+ * follow-up updates within the window are coalesced into one trailing flush.
  */
 
 import * as Y from "yjs";
@@ -19,18 +20,15 @@ import type { OfflineStore } from "./OfflineStore.ts";
  * Attach an observer that writes `updatedAt` to the root doc-tree entry for
  * `childDocId` whenever the child doc receives a non-offline update.
  *
- * Writes are throttled: the first qualifying update records the timestamp;
- * a trailing-edge timer flushes it to the tree map after `throttleMs`.
- *
  * @param treeMap       The root doc's "doc-tree" Y.Map.
  * @param childDocId    The child document's UUID (key in treeMap).
  * @param childDoc      The child Y.Doc to observe.
  * @param offlineStore  The child provider's OfflineStore (used to detect
  *                      offline-replay origins and skip them). Pass null when
  *                      the offline store is disabled.
- * @param options       Optional config. `throttleMs` controls the write
- *                      interval (default 5000).
- * @returns             Cleanup function — call on provider destroy.  Flushes
+ * @param options       Optional config. `throttleMs` controls the throttle
+ *                      window (default 5000).
+ * @returns             Cleanup function — call on provider destroy. Flushes
  *                      any pending write before detaching.
  */
 export function attachUpdatedAtObserver(
@@ -42,34 +40,39 @@ export function attachUpdatedAtObserver(
 ): () => void {
 	const throttleMs = options?.throttleMs ?? 5000;
 
-	let latestTs = 0;
+	let lastFlushedAt = 0;
+	let pendingTs = 0;
 	let timer: ReturnType<typeof setTimeout> | null = null;
 
-	function flush(): void {
-		if (latestTs === 0) return;
-		const ts = latestTs;
-		latestTs = 0;
-		timer = null;
-
+	function writeTs(ts: number): void {
 		const raw = treeMap.get(childDocId);
 		if (!raw) return;
-
-		// Guard: if the entry is a nested Y.Map (possible after Yrs
-		// document compaction), convert to plain object so spread works.
 		const entry = raw instanceof Y.Map ? (raw as any).toJSON() : raw;
 		treeMap.set(childDocId, { ...entry, updatedAt: ts });
+		lastFlushedAt = ts;
+	}
+
+	function flushPending(): void {
+		timer = null;
+		if (pendingTs === 0) return;
+		const ts = pendingTs;
+		pendingTs = 0;
+		writeTs(ts);
 	}
 
 	function handler(_update: Uint8Array, origin: unknown): void {
-		// Skip updates replayed from the local offline store — they represent
-		// content that was already "seen" and shouldn't advance updatedAt.
 		if (offlineStore !== null && origin === offlineStore) return;
 
-		latestTs = Date.now();
-
-		// Schedule a trailing-edge flush if none is pending.
+		const now = Date.now();
+		if (now - lastFlushedAt >= throttleMs) {
+			// Leading edge — flush immediately.
+			writeTs(now);
+			return;
+		}
+		// Inside the throttle window — coalesce into a trailing flush.
+		pendingTs = now;
 		if (timer === null) {
-			timer = setTimeout(flush, throttleMs);
+			timer = setTimeout(flushPending, throttleMs - (now - lastFlushedAt));
 		}
 	}
 
@@ -79,7 +82,7 @@ export function attachUpdatedAtObserver(
 		childDoc.off("update", handler);
 		if (timer !== null) {
 			clearTimeout(timer);
-			flush(); // persist the last pending timestamp
+			flushPending();
 		}
 	};
 }

package/src/index.ts

@@ -37,8 +37,52 @@ export type {
 } from "./IdentityDoc.ts";
 export { DeviceRegistrationService } from "./DeviceRegistrationService.ts";
 export { ChatClient } from "./ChatClient.ts";
-export type { ChatClientTransport } from "./ChatClient.ts";
+export { RpcClient, RpcError, RPC_PREFIX } from "./RpcClient.ts";
+export type {
+	RpcKind,
+	RpcFrame,
+	RpcErrorPayload,
+	RpcErrorCode,
+	RpcTransport,
+	RpcTarget,
+	RpcCallOptions,
+	RpcCallHandle,
+	RpcHandler,
+	RpcHandlerContext,
+} from "./RpcClient.ts";
+export type {
+	ChatClientTransport,
+	SendMessageInput,
+	SendMessageResult,
+	EditMessageInput,
+	DeleteMessageInput,
+	MarkReadInput as ChatMarkReadInput,
+} from "./ChatClient.ts";
+export {
+	EncryptedChatClient,
+	ChannelKeyResolver,
+	encryptChatContent,
+	decryptChatContent,
+	isEncryptedContent,
+} from "./EncryptedChatClient.ts";
+export {
+	foldRecords,
+	recordFromYAny,
+} from "./messageRecord.ts";
+export type {
+	MessageRecord,
+	FoldedMessage,
+} from "./messageRecord.ts";
 export { NotificationsClient } from "./NotificationsClient.ts";
+export type {
+	InboxEntry,
+	FetchInboxInput,
+	MarkReadInput as InboxMarkReadInput,
+} from "./NotificationsClient.ts";
+// Legacy type re-exports — wire-shape types from the deprecated chat:* / notify:*
+// protocol that consumers may still import. The dashboard's reactive layer
+// reads/writes these shapes directly off Y.Array entries on channel-period and
+// inbox docs, independently of ChatClient/NotificationsClient.
 export type {
 	ChatMessage,
 	ChatChannel,
@@ -62,3 +106,29 @@ export {
 	unwrapSeed,
 	bip39Wordlist,
 } from "./MnemonicKeyDerivation.ts";
+export { DocumentManager } from "./DocumentManager.ts";
+export type { DocumentManagerConfig } from "./DocumentManager.ts";
+export { TreeManager } from "./TreeManager.ts";
+export { ContentManager } from "./ContentManager.ts";
+export type { DocumentContent } from "./ContentManager.ts";
+export { MetaManager } from "./MetaManager.ts";
+export type { DocumentMetaInfo } from "./MetaManager.ts";
+export * from "./DocTypes.ts";
+export { waitForSync, withTimeout, normalizeRootId, toPlain } from "./DocUtils.ts";
+export {
+	yjsToMarkdown,
+	populateYDocFromMarkdown,
+	parseFrontmatter,
+	filenameToLabel,
+	buildHeadingElement,
+	buildParagraphElement,
+	buildBulletListElement,
+	buildOrderedListElement,
+	buildTaskListElement,
+	buildCodeBlockElement,
+	buildBlockquoteElement,
+	buildHorizontalRuleElement,
+	buildBlocksFromMarkdown,
+	readBlocksFromFragment,
+} from "./DocConverters.ts";
+export type { DocumentBlock } from "./DocConverters.ts";