AI-native knowledge base & Evernote/Obsidian alternative with instant sync & native MCP. Free on Cloudflare or self-hosted via Docker.
HTML ai-agentcloudflarecloudflare-d1cloudflare-r2cloudflare-workersdockerelectronevernoteevernote-alternativeknowledge-basemcpnote-takingobsidian-alternativeoffline-firstpersonal-knowledge-basepwaself-hostedsqlitetiptapweb-clipper
import { docToText, markdownToDoc } from "./content";
import type { MemoDetail } from "./types";
import {
ARCHITECTURE_RESOURCE_ICONS,
DIAGRAM_THEMES,
DIAGRAM_STRUCTURES,
parseDiagramDocument,
serializeDiagramDocument,
stripDiagramDocumentMarker,
type DiagramDocument,
type DiagramNodeShape,
} from "./diagram";
import type { DiagramIr, DiagramIrNodeType } from "./diagram-layout";
import { StructuredNoteError, requiredStructuredString as getRequiredString } from "./structured-note-error";
const createId = (prefix: string) => `${prefix}_${crypto.randomUUID().replace(/-/g, "")}`;
const DIAGRAM_IR_NODE_TYPES = new Set<DiagramIrNodeType>([
"topic", "process", "decision", "start", "end", "terminator", "client", "frontend", "service", "database", "storage",
"queue", "security", "external", "boundary",
]);
const DIAGRAM_EDGE_KINDS = new Set(["dependency", "request", "async", "data"]);
const DIAGRAM_MEMO_KEYS = new Set(["notebookId", "title", "kind", "theme", "structure", "layout", "tags", "nodes", "edges"]);
const DIAGRAM_NODE_KEYS = new Set(["id", "label", "type", "parentId", "resourceIcon"]);
const DIAGRAM_EDGE_KEYS = new Set(["source", "target", "label", "type", "bidirectional"]);
const isPlainRecord = (value: unknown): value is Record<string, unknown> =>
Boolean(value) && typeof value === "object" && !Array.isArray(value);
const assertAllowedKeys = (value: Record<string, unknown>, allowed: Set<string>, path: string) => {
const unexpected = Object.keys(value).find((key) => !allowed.has(key));
if (unexpected) throw new StructuredNoteError("invalid_params", `${path}.${unexpected} is not supported`, 400);
};
const parseDiagramNode = (value: unknown, index: number) => {
const path = `nodes.${index}`;
if (!isPlainRecord(value)) throw new StructuredNoteError("invalid_params", `${path} must be an object`, 400);
assertAllowedKeys(value, DIAGRAM_NODE_KEYS, path);
const id = getRequiredString(value.id, `${path}.id`);
if (id.length > 100) throw new StructuredNoteError("invalid_params", `${path}.id must be at most 100 characters`, 400);
if (typeof value.label !== "string" || value.label.length > 500) {
throw new StructuredNoteError("invalid_params", `${path}.label must be a string with at most 500 characters`, 400);
}
if (value.type !== undefined && (
typeof value.type !== "string" || !DIAGRAM_IR_NODE_TYPES.has(value.type as DiagramIrNodeType)
)) {
throw new StructuredNoteError("invalid_params", `${path}.type is not supported`, 400);
}
if (value.parentId !== undefined && (typeof value.parentId !== "string" || !value.parentId.trim() || value.parentId.length > 100)) {
throw new StructuredNoteError("invalid_params", `${path}.parentId must be a non-empty string with at most 100 characters`, 400);
}
if (value.resourceIcon !== undefined && (
typeof value.resourceIcon !== "string"
|| !ARCHITECTURE_RESOURCE_ICONS.includes(value.resourceIcon as typeof ARCHITECTURE_RESOURCE_ICONS[number])
)) {
throw new StructuredNoteError("invalid_params", `${path}.resourceIcon is not supported`, 400);
}
return { ...value, id } as DiagramIr["nodes"][number];
};
const parseDiagramEdge = (value: unknown, index: number) => {
const path = `edges.${index}`;
if (!isPlainRecord(value)) throw new StructuredNoteError("invalid_params", `${path} must be an object`, 400);
assertAllowedKeys(value, DIAGRAM_EDGE_KEYS, path);
const source = getRequiredString(value.source, `${path}.source`);
const target = getRequiredString(value.target, `${path}.target`);
if ([source, target].some((item) => item.length > 100)) {
throw new StructuredNoteError("invalid_params", `${path} node IDs must be at most 100 characters`, 400);
}
if (value.label !== undefined && (typeof value.label !== "string" || value.label.length > 500)) {
throw new StructuredNoteError("invalid_params", `${path}.label must be a string with at most 500 characters`, 400);
}
if (value.type !== undefined && (typeof value.type !== "string" || !DIAGRAM_EDGE_KINDS.has(value.type))) {
throw new StructuredNoteError("invalid_params", `${path}.type is not supported`, 400);
}
if (value.bidirectional !== undefined && typeof value.bidirectional !== "boolean") {
throw new StructuredNoteError("invalid_params", `${path}.bidirectional must be a boolean`, 400);
}
return { ...value, source, target } as NonNullable<DiagramIr["edges"]>[number];
};
export const parseDiagramMemoIr = (args: Record<string, unknown>): DiagramIr => {
assertAllowedKeys(args, DIAGRAM_MEMO_KEYS, "arguments");
const kind = getRequiredString(args.kind, "kind");
if (!(["mind-map", "flowchart", "architecture"] as const).includes(kind as DiagramIr["kind"])) {
throw new StructuredNoteError("invalid_params", "kind must be mind-map, flowchart, or architecture", 400);
}
if (!Array.isArray(args.nodes) || args.nodes.length < 1 || args.nodes.length > 200) {
throw new StructuredNoteError("invalid_params", "nodes must include between 1 and 200 items", 400);
}
if (args.edges !== undefined && (!Array.isArray(args.edges) || args.edges.length > 400)) {
throw new StructuredNoteError("invalid_params", "edges must be an array with at most 400 items", 400);
}
if (args.theme !== undefined && !(DIAGRAM_THEMES as readonly string[]).includes(String(args.theme))) {
throw new StructuredNoteError("invalid_params", "theme is not a supported diagram color scheme", 400);
}
if (args.structure !== undefined && !(DIAGRAM_STRUCTURES as readonly string[]).includes(String(args.structure))) {
throw new StructuredNoteError("invalid_params", "structure is not a supported mind-map shape", 400);
}
if (args.title !== undefined && (typeof args.title !== "string" || args.title.length > 160)) {
throw new StructuredNoteError("invalid_params", "title must be a string with at most 160 characters", 400);
}
if (args.tags !== undefined && (
!Array.isArray(args.tags) || args.tags.length > 100 || args.tags.some((tag) => typeof tag !== "string")
)) {
throw new StructuredNoteError("invalid_params", "tags must be an array of at most 100 strings", 400);
}
if (args.layout !== undefined && (
!isPlainRecord(args.layout)
|| Object.keys(args.layout).some((key) => key !== "direction")
|| (args.layout.direction !== undefined && !["left-to-right", "top-to-bottom"].includes(String(args.layout.direction)))
)) {
throw new StructuredNoteError("invalid_params", "layout may only specify direction as left-to-right or top-to-bottom", 400);
}
const ir: DiagramIr = {
kind: kind as DiagramIr["kind"],
...(args.theme === undefined ? {} : { theme: args.theme as DiagramIr["theme"] }),
...(args.structure === undefined ? {} : { structure: args.structure as DiagramIr["structure"] }),
...(args.layout === undefined ? {} : { layout: args.layout as DiagramIr["layout"] }),
nodes: args.nodes.map(parseDiagramNode),
edges: (args.edges as unknown[] | undefined)?.map(parseDiagramEdge),
};
const nodeIds = new Set(ir.nodes.map((node) => node.id));
if (nodeIds.size !== ir.nodes.length) throw new StructuredNoteError("invalid_params", "node IDs must be unique", 400);
for (const node of ir.nodes) {
const allowedTypes = ir.kind === "mind-map"
? new Set([undefined, "topic"])
: ir.kind === "flowchart"
? new Set([undefined, "process", "decision", "start", "end", "terminator"])
: new Set([undefined, "client", "frontend", "service", "database", "storage", "queue", "security", "external", "boundary"]);
if (!allowedTypes.has(node.type)) {
throw new StructuredNoteError("invalid_params", `${node.type} is not a valid node type for ${ir.kind}`, 400);
}
if (ir.kind === "flowchart" && node.parentId) {
throw new StructuredNoteError("invalid_params", "flowchart nodes cannot use parentId", 400);
}
if (ir.kind !== "architecture" && node.resourceIcon) {
throw new StructuredNoteError("invalid_params", "resourceIcon is only available for architecture nodes", 400);
}
if (node.parentId && !nodeIds.has(node.parentId)) {
throw new StructuredNoteError("invalid_params", `${node.id}.parentId must reference an existing node`, 400);
}
if (ir.kind === "architecture" && node.parentId && ir.nodes.find((candidate) => candidate.id === node.parentId)?.type !== "boundary") {
throw new StructuredNoteError("invalid_params", `${node.id}.parentId must reference an architecture boundary`, 400);
}
}
for (const edge of ir.edges ?? []) {
if (!nodeIds.has(edge.source) || !nodeIds.has(edge.target)) {
throw new StructuredNoteError("invalid_params", "every edge endpoint must reference an existing node", 400);
}
if (ir.kind === "architecture" && ir.nodes.some((node) => (node.id === edge.source || node.id === edge.target) && node.type === "boundary")) {
throw new StructuredNoteError("invalid_params", "architecture boundaries cannot be edge endpoints", 400);
}
}
const parentByNodeId = new Map(ir.nodes.flatMap((node) => node.parentId ? [[node.id, node.parentId]] : []));
for (const node of ir.nodes) {
const ancestors = new Set<string>();
let currentId: string | undefined = node.id;
while (currentId) {
if (ancestors.has(currentId)) {
throw new StructuredNoteError("invalid_params", "diagram parent relationships must not contain cycles", 400);
}
ancestors.add(currentId);
currentId = parentByNodeId.get(currentId);
}
}
return ir;
};
const diagramNodeType = (shape: DiagramNodeShape): DiagramIrNodeType => shape;
export const diagramSemanticGraph = (document: DiagramDocument, includeLayout = false) => ({
kind: document.kind,
...(document.theme ? { theme: document.theme } : {}),
...(document.structure ? { structure: document.structure } : {}),
nodes: document.nodes.map((node) => ({
id: node.id,
label: node.label,
type: diagramNodeType(node.shape),
...(node.parentId ? { parentId: node.parentId } : {}),
...(node.resourceIcon ? { resourceIcon: node.resourceIcon } : {}),
...(includeLayout ? { layout: { x: node.x, y: node.y, width: node.width, height: node.height } } : {}),
})),
edges: document.edges.map((edge) => ({
id: edge.id,
source: edge.source,
target: edge.target,
...(edge.label ? { label: edge.label } : {}),
...(edge.kind ? { type: edge.kind } : {}),
...(edge.bidirectional !== undefined ? { bidirectional: edge.bidirectional } : {}),
})),
});
export const memoWithoutDiagramPayload = (memo: MemoDetail) => {
const contentMarkdown = stripDiagramDocumentMarker(memo.contentMarkdown);
const contentJson = markdownToDoc(contentMarkdown);
return { ...memo, contentMarkdown, contentJson, contentText: docToText(contentJson) };
};
type MutableDiagramEdge = ReturnType<typeof diagramSemanticGraph>["edges"][number];
export const applyDiagramOperations = async (
args: Record<string, unknown>,
current: DiagramDocument,
) => {
assertAllowedKeys(args, new Set(["memoId", "expectedRevision", "operations", "dryRun", "reflow"]), "arguments");
if (!Array.isArray(args.operations) || args.operations.length < 1 || args.operations.length > 100) {
throw new StructuredNoteError("invalid_params", "operations must include between 1 and 100 items", 400);
}
if (args.reflow !== undefined && args.reflow !== "preserve" && args.reflow !== "all") {
throw new StructuredNoteError("invalid_params", "reflow must be preserve or all", 400);
}
let nodes: DiagramIr["nodes"] = current.nodes.map((node) => ({
id: node.id,
label: node.label,
type: diagramNodeType(node.shape),
...(node.parentId ? { parentId: node.parentId } : {}),
...(node.resourceIcon ? { resourceIcon: node.resourceIcon } : {}),
}));
let edges: MutableDiagramEdge[] = diagramSemanticGraph(current).edges;
const resizedNodeIds = new Set<string>();
const repositionedNodeIds = new Set<string>();
const affectedBoundaryIds = new Set<string>();
const counts = { addedNodes: 0, updatedNodes: 0, removedNodes: 0, addedEdges: 0, updatedEdges: 0, removedEdges: 0 };
const requireOperation = (value: unknown, index: number) => {
if (!isPlainRecord(value) || typeof value.op !== "string") {
throw new StructuredNoteError("invalid_params", `operations.${index} must be an object with an op`, 400);
}
return value;
};
const findNodeIndex = (nodeId: string) => {
const index = nodes.findIndex((node) => node.id === nodeId);
if (index < 0) throw new StructuredNoteError("invalid_params", `diagram node ${nodeId} does not exist`, 400);
return index;
};
const findEdgeIndex = (edgeId: string) => {
const index = edges.findIndex((edge) => edge.id === edgeId);
if (index < 0) throw new StructuredNoteError("invalid_params", `diagram edge ${edgeId} does not exist`, 400);
return index;
};
for (let operationIndex = 0; operationIndex < args.operations.length; operationIndex += 1) {
const operation = requireOperation(args.operations[operationIndex], operationIndex);
const path = `operations.${operationIndex}`;
if (operation.op === "add_node") {
assertAllowedKeys(operation, new Set(["op", "node"]), path);
const node = parseDiagramNode(operation.node, operationIndex);
if (nodes.some((candidate) => candidate.id === node.id)) {
throw new StructuredNoteError("invalid_params", `diagram node ${node.id} already exists`, 400);
}
nodes.push(node);
if (node.parentId) affectedBoundaryIds.add(node.parentId);
counts.addedNodes += 1;
continue;
}
if (operation.op === "update_node") {
assertAllowedKeys(operation, new Set(["op", "nodeId", "changes"]), path);
const nodeId = getRequiredString(operation.nodeId, `${path}.nodeId`);
if (!isPlainRecord(operation.changes) || Object.keys(operation.changes).length === 0) {
throw new StructuredNoteError("invalid_params", `${path}.changes must be a non-empty object`, 400);
}
assertAllowedKeys(operation.changes, new Set(["label", "type", "parentId", "resourceIcon"]), `${path}.changes`);
const index = findNodeIndex(nodeId);
const previous = nodes[index];
const candidate: Record<string, unknown> = { ...previous, ...operation.changes, id: nodeId };
if (operation.changes.parentId === null || operation.changes.parentId === "") delete candidate.parentId;
if (operation.changes.resourceIcon === null || operation.changes.resourceIcon === "") delete candidate.resourceIcon;
const next = parseDiagramNode(candidate, operationIndex);
nodes[index] = next;
if (operation.changes.label !== undefined || operation.changes.type !== undefined) resizedNodeIds.add(nodeId);
if (operation.changes.parentId !== undefined && previous.parentId !== next.parentId) {
repositionedNodeIds.add(nodeId);
if (previous.parentId) affectedBoundaryIds.add(previous.parentId);
if (next.parentId) affectedBoundaryIds.add(next.parentId);
}
counts.updatedNodes += 1;
continue;
}
if (operation.op === "remove_node") {
assertAllowedKeys(operation, new Set(["op", "nodeId", "cascade"]), path);
const nodeId = getRequiredString(operation.nodeId, `${path}.nodeId`);
findNodeIndex(nodeId);
const removalIds = new Set([nodeId]);
let changed = true;
while (changed) {
changed = false;
for (const node of nodes) {
if (node.parentId && removalIds.has(node.parentId) && !removalIds.has(node.id)) {
if (operation.cascade !== true) {
throw new StructuredNoteError("invalid_params", `${nodeId} contains child nodes; set cascade to true to remove them`, 400);
}
removalIds.add(node.id);
changed = true;
}
}
}
for (const node of nodes) if (removalIds.has(node.id) && node.parentId) affectedBoundaryIds.add(node.parentId);
const priorEdgeCount = edges.length;
nodes = nodes.filter((node) => !removalIds.has(node.id));
edges = edges.filter((edge) => !removalIds.has(edge.source) && !removalIds.has(edge.target));
counts.removedNodes += removalIds.size;
counts.removedEdges += priorEdgeCount - edges.length;
continue;
}
if (operation.op === "add_edge") {
assertAllowedKeys(operation, new Set(["op", "edge"]), path);
if (!isPlainRecord(operation.edge)) throw new StructuredNoteError("invalid_params", `${path}.edge must be an object`, 400);
assertAllowedKeys(operation.edge, new Set([...DIAGRAM_EDGE_KEYS, "id"]), `${path}.edge`);
const { id: requestedId, ...edgeInput } = operation.edge;
const parsed = parseDiagramEdge(edgeInput, operationIndex);
const id = requestedId === undefined ? createId("edge") : getRequiredString(requestedId, `${path}.edge.id`);
if (id.length > 100 || edges.some((edge) => edge.id === id)) {
throw new StructuredNoteError("invalid_params", `diagram edge ID ${id} is invalid or already exists`, 400);
}
edges.push({ id, ...parsed });
counts.addedEdges += 1;
continue;
}
if (operation.op === "update_edge") {
assertAllowedKeys(operation, new Set(["op", "edgeId", "changes"]), path);
const edgeId = getRequiredString(operation.edgeId, `${path}.edgeId`);
if (!isPlainRecord(operation.changes) || Object.keys(operation.changes).length === 0) {
throw new StructuredNoteError("invalid_params", `${path}.changes must be a non-empty object`, 400);
}
assertAllowedKeys(operation.changes, DIAGRAM_EDGE_KEYS, `${path}.changes`);
const index = findEdgeIndex(edgeId);
const candidate: Record<string, unknown> = { ...edges[index], ...operation.changes };
delete candidate.id;
if (operation.changes.label === null || operation.changes.label === "") delete candidate.label;
if (operation.changes.type === null || operation.changes.type === "") delete candidate.type;
if (operation.changes.bidirectional === null) delete candidate.bidirectional;
edges[index] = { id: edgeId, ...parseDiagramEdge(candidate, operationIndex) };
counts.updatedEdges += 1;
continue;
}
if (operation.op === "remove_edge") {
assertAllowedKeys(operation, new Set(["op", "edgeId"]), path);
const edgeId = getRequiredString(operation.edgeId, `${path}.edgeId`);
edges.splice(findEdgeIndex(edgeId), 1);
counts.removedEdges += 1;
continue;
}
throw new StructuredNoteError("invalid_params", `${path}.op is not supported`, 400);
}
if (nodes.length < 1) throw new StructuredNoteError("invalid_params", "a diagram must contain at least one node", 400);
if (current.kind === "mind-map") {
const priorEdgeCount = edges.length;
edges = edges.filter((edge) => !repositionedNodeIds.has(edge.target)
|| nodes.find((node) => node.id === edge.target)?.parentId === edge.source);
counts.removedEdges += priorEdgeCount - edges.length;
for (const node of nodes) {
if (!node.parentId || edges.some((edge) => edge.source === node.parentId && edge.target === node.id)) continue;
edges.push({ id: createId("edge"), source: node.parentId, target: node.id });
counts.addedEdges += 1;
}
}
const validatedIr = parseDiagramMemoIr({
kind: current.kind,
...(current.theme ? { theme: current.theme } : {}),
...(current.structure ? { structure: current.structure } : {}),
nodes,
edges: edges.map(({ id: _id, ...edge }) => edge),
});
const { compileDiagramIr } = await import("./diagram-layout");
const next = compileDiagramIr(validatedIr);
// Editing content must preserve the persisted visual identity.
next.theme = current.theme;
next.structure = current.structure;
next.edges = edges.map((edge) => ({
id: edge.id,
source: edge.source,
target: edge.target,
...(edge.label ? { label: edge.label } : {}),
...(edge.type ? { kind: edge.type } : {}),
...(edge.bidirectional !== undefined ? { bidirectional: edge.bidirectional } : {}),
}));
if (args.reflow !== "all") {
const currentById = new Map(current.nodes.map((node) => [node.id, node]));
for (const node of next.nodes) {
const previous = currentById.get(node.id);
if (!previous) continue;
const boundaryNeedsLayout = node.shape === "boundary" && affectedBoundaryIds.has(node.id);
if (repositionedNodeIds.has(node.id) || boundaryNeedsLayout) continue;
node.x = previous.x;
node.y = previous.y;
if (!resizedNodeIds.has(node.id)) {
node.width = previous.width;
node.height = previous.height;
}
}
if (current.kind === "architecture" && affectedBoundaryIds.size > 0) {
const nodeById = new Map(next.nodes.map((node) => [node.id, node]));
for (const boundaryId of Array.from(affectedBoundaryIds)) {
let parentId = nodeById.get(boundaryId)?.parentId;
while (parentId) {
affectedBoundaryIds.add(parentId);
parentId = nodeById.get(parentId)?.parentId;
}
}
const depth = (nodeId: string) => {
let result = 0;
let node = nodeById.get(nodeId);
while (node?.parentId) {
result += 1;
node = nodeById.get(node.parentId);
}
return result;
};
for (const boundaryId of [...affectedBoundaryIds].sort((left, right) => depth(right) - depth(left))) {
const boundary = nodeById.get(boundaryId);
const children = next.nodes.filter((node) => node.parentId === boundaryId);
if (!boundary || boundary.shape !== "boundary" || children.length === 0) continue;
const left = Math.min(...children.map((node) => node.x)) - 36;
const top = Math.min(...children.map((node) => node.y)) - 56;
const right = Math.max(...children.map((node) => node.x + node.width)) + 36;
const bottom = Math.max(...children.map((node) => node.y + node.height)) + 36;
boundary.x = left;
boundary.y = top;
boundary.width = Math.max(260, right - left);
boundary.height = Math.max(180, bottom - top);
}
}
}
const contentMarkdown = serializeDiagramDocument(next);
if (!parseDiagramDocument(contentMarkdown)) {
throw new StructuredNoteError("invalid_params", "The diagram operations produced an invalid document", 400);
}
return { document: next, contentMarkdown, changes: counts };
};