npm - collabmd - Versions diffs - 0.1.48 → 0.1.49 - Mend

collabmd 0.1.48 → 0.1.49

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (268) hide show

package/src/domain/collabmd-content-capabilities.js ADDED Viewed

@@ -0,0 +1,149 @@
+import {
+  BASE_FILE_EXTENSION,
+  DRAWIO_FILE_EXTENSION,
+  EXCALIDRAW_FILE_EXTENSION,
+  HTML_FILE_EXTENSIONS,
+  IMAGE_ATTACHMENT_EXTENSIONS,
+  MARKDOWN_FILE_EXTENSIONS,
+  MERMAID_FILE_EXTENSIONS,
+  PDF_FILE_EXTENSION,
+  PLANTUML_FILE_EXTENSIONS,
+  STRUCTURIZR_FILE_EXTENSIONS,
+  getVaultFileKind,
+  supportsCommentsForFilePath,
+} from './file-kind.js';
+const CAPABILITIES = Object.freeze({
+  base: {
+    agentCreatable: false,
+    agentEditable: false,
+    editable: true,
+    extensions: [BASE_FILE_EXTENSION],
+    guide: 'YAML Base definition. Embed a file with ![[query.base]] or an inline query with a fenced base block. Agent writes are disabled until Base validation is shared.',
+    examples: ['```base\nfilters:\n  and: []\n```', '![[tasks.base]]'],
+  },
+  drawio: {
+    agentCreatable: false,
+    agentEditable: false,
+    editable: true,
+    extensions: [DRAWIO_FILE_EXTENSION],
+    guide: 'diagrams.net XML managed by the embedded draw.io editor. Embed with ![[architecture.drawio]]. Agent writes are disabled.',
+    examples: ['![[architecture.drawio]]'],
+  },
+  excalidraw: {
+    agentCreatable: true,
+    agentEditable: true,
+    editable: true,
+    extensions: [EXCALIDRAW_FILE_EXTENSION],
+    guide: 'Excalidraw scene JSON managed by the canvas editor. Use create_excalidraw and edit_excalidraw rather than raw text edits. Element order is back-to-front; create supports beforeElementId and afterElementId, while edit supports relationship-aware translation, reorder, same-ID replace, and same-revision verification. Container or group translation also moves bound text and grouped members. Standalone auto-resizing text recalculates its bounds when text metrics change. Line, arrow, and freedraw dimensions are derived from points. Creation and editing support inline inspection and optional rendering; remote fallback renders report preview-not-pixel-identical. Supported agent element types: rectangle, ellipse, diamond, text, arrow, line, and freedraw. Embed with ![[drawing.excalidraw]].',
+    examples: ['![[drawing.excalidraw]]'],
+  },
+  html: {
+    agentCreatable: true,
+    agentEditable: true,
+    editable: true,
+    extensions: [...HTML_FILE_EXTENSIONS],
+    guide: 'Standalone HTML file. Raw HTML inside Markdown is escaped; use a standalone .html or .htm file when HTML is required.',
+    examples: ['<!doctype html>\n<html lang="en"><body><h1>Title</h1></body></html>'],
+  },
+  image: {
+    agentCreatable: false,
+    agentEditable: false,
+    editable: false,
+    extensions: [...IMAGE_ATTACHMENT_EXTENSIONS],
+    guide: 'Binary or SVG attachment. Reference from Markdown with a relative image path. Use attachment upload rather than create_document.',
+    examples: ['![Diagram](assets/diagram.png)'],
+  },
+  markdown: {
+    agentCreatable: true,
+    agentEditable: true,
+    editable: true,
+    extensions: [...MARKDOWN_FILE_EXTENSIONS],
+    guide: 'Markdown-it syntax with YAML frontmatter, headings, tables, task lists, fenced code, linkified URLs, [[wiki-links]], aliases, and embeds. Use ![[file.ext]] for Base, draw.io, Excalidraw, Mermaid, or PlantUML Vault embeds. Use ![Label](https://...) for public video embeds: valid YouTube URLs or direct public HTTPS URLs ending in .mp4, .webm, or .ogg. Use relative Markdown image paths for Vault image attachments. Raw HTML is disabled.',
+    examples: [
+      '---\ntags: [docs]\n---\n# Title\n\n- [ ] Task\n\n[[Other Note|Alias]]',
+      '![[diagram.mmd]]\n![[diagram.puml]]\n![[drawing.excalidraw]]\n![[architecture.drawio]]\n![[query.base]]',
+      '![Demo](https://www.youtube.com/watch?v=dQw4w9WgXcQ)\n![Demo](https://cdn.example.com/demo.webm)\n![Diagram](assets/diagram.png)',
+      '```mermaid\nflowchart LR\n  A --> B\n```\n\n```plantuml\n@startuml\nAlice -> Bob\n@enduml\n```',
+    ],
+  },
+  mermaid: {
+    agentCreatable: true,
+    agentEditable: true,
+    editable: true,
+    extensions: [...MERMAID_FILE_EXTENSIONS],
+    guide: 'Standalone Mermaid source. Markdown also supports fenced mermaid blocks and ![[diagram.mmd]] embeds.',
+    examples: ['flowchart LR\n  A[Start] --> B[Done]'],
+  },
+  pdf: {
+    agentCreatable: false,
+    agentEditable: false,
+    editable: false,
+    extensions: [PDF_FILE_EXTENSION],
+    guide: 'Readonly PDF Vault Content. Agent text tools do not read or write PDF bytes.',
+    examples: [],
+  },
+  plantuml: {
+    agentCreatable: true,
+    agentEditable: true,
+    editable: true,
+    extensions: [...PLANTUML_FILE_EXTENSIONS],
+    guide: 'Standalone PlantUML source, normally enclosed by @startuml and @enduml. Markdown supports plantuml or puml fences and ![[diagram.puml]] embeds.',
+    examples: ['@startuml\nAlice -> Bob : Hello\n@enduml'],
+  },
+  structurizr: {
+    agentCreatable: true,
+    agentEditable: true,
+    editable: true,
+    extensions: [...STRUCTURIZR_FILE_EXTENSIONS],
+    guide: 'Structurizr DSL C4 workspace. Preview requires configured Structurizr renderer.',
+    examples: ['workspace {\n  model {\n    user = person "User"\n    system = softwareSystem "System"\n    user -> system "Uses"\n  }\n  views { systemContext system { include * } }\n}'],
+  },
+});
+function resolveKind(kindOrPath) {
+  const normalized = String(kindOrPath ?? '').trim().toLowerCase();
+  return Object.hasOwn(CAPABILITIES, normalized) ? normalized : getVaultFileKind(normalized);
+}
+export function getCollabMdContentCapability(kindOrPath) {
+  const kind = resolveKind(kindOrPath);
+  if (!kind || !CAPABILITIES[kind]) return null;
+  const capability = CAPABILITIES[kind];
+  const commentPath = capability.extensions[0] ? `file${capability.extensions[0]}` : '';
+  return {
+    ...capability,
+    commentsSupported: commentPath ? supportsCommentsForFilePath(commentPath) : false,
+    kind,
+    readable: capability.editable,
+    searchable: kind !== 'image' && kind !== 'pdf',
+  };
+}
+export function listCollabMdContentCapabilities() {
+  return Object.keys(CAPABILITIES).map(getCollabMdContentCapability);
+}
+export function getCollabMdSyntaxGuide(kind) {
+  const capability = getCollabMdContentCapability(kind);
+  return capability ? {
+    examples: capability.examples,
+    extensions: capability.extensions,
+    guide: capability.guide,
+    kind: capability.kind,
+  } : null;
+}
+export function isAgentReadablePath(path) {
+  return Boolean(getCollabMdContentCapability(path)?.readable);
+}
+export function isAgentEditablePath(path) {
+  const capability = getCollabMdContentCapability(path);
+  return Boolean(capability?.agentEditable && capability.kind !== 'excalidraw');
+}
+export function isAgentCreatablePath(path) {
+  const capability = getCollabMdContentCapability(path);
+  return Boolean(capability?.agentCreatable && capability.kind !== 'excalidraw');
+}

package/src/domain/collaboration-protocol.js ADDED Viewed

	@@ -0,0 +1,2 @@
1	+ export const MSG_AGENT_FLUSH = 4;
2	+ export const MSG_AGENT_FLUSH_ACK = 5;

package/src/domain/comment-threads.js CHANGED Viewed

@@ -219,11 +219,9 @@ function serializeMessages(messages) {
 }
 export function createCommentId(prefix = 'comment') {
-  if (globalThis.crypto?.randomUUID) {
-    return `${prefix}-${globalThis.crypto.randomUUID()}`;
-  }
-  return `${prefix}-${Date.now()}-${Math.random().toString(36).slice(2, 10)}`;
+  const id = globalThis.crypto?.randomUUID?.()
+    ?? `${Date.now()}-${Math.random().toString(36).slice(2, 10)}`;
+  return `${prefix}-${id}`;
 }
 export function normalizeCommentAnchor(record = {}) {

package/src/domain/diagram-source.js ADDED Viewed

@@ -0,0 +1,50 @@
+import { getVaultFileKind } from './file-kind.js';
+const FENCE_OPEN_PATTERN = /^\s*(`{3,})(mermaid|plantuml|puml)\s*$/iu;
+export function listRenderableDiagrams(content = '', path = '', { contentStartLine = 1 } = {}) {
+  const kind = getVaultFileKind(path);
+  const lines = String(content).split('\n');
+  if (kind === 'mermaid' || kind === 'plantuml') {
+    return [{
+      endLine: contentStartLine + Math.max(lines.length - 1, 0),
+      kind,
+      source: String(content),
+      startLine: contentStartLine,
+    }];
+  }
+  if (kind !== 'markdown') return [];
+  const diagrams = [];
+  for (let index = 0; index < lines.length; index += 1) {
+    const match = lines[index].match(FENCE_OPEN_PATTERN);
+    if (!match) continue;
+    const fence = match[1];
+    const diagramKind = match[2].toLowerCase() === 'mermaid' ? 'mermaid' : 'plantuml';
+    const sourceStart = index + 1;
+    let end = sourceStart;
+    while (end < lines.length && lines[end].trim() !== fence) {
+      end += 1;
+    }
+    if (end >= lines.length) continue;
+    diagrams.push({
+      endLine: contentStartLine + end,
+      kind: diagramKind,
+      source: lines.slice(sourceStart, end).join('\n'),
+      startLine: contentStartLine + index,
+    });
+    index = end;
+  }
+  return diagrams;
+}
+export function resolveRenderableDiagram(content = '', path = '', options = {}) {
+  const diagrams = listRenderableDiagrams(content, path, options);
+  const requestedStartLine = Number.parseInt(options.startLine, 10);
+  if (Number.isInteger(requestedStartLine)) {
+    return diagrams.find(({ startLine }) => startLine === requestedStartLine) ?? null;
+  }
+  return diagrams.length === 1 ? diagrams[0] : null;
+}

package/src/domain/editable-content-revision.js ADDED Viewed

@@ -0,0 +1,10 @@
+export async function createEditableContentRevision(content) {
+  const digest = await globalThis.crypto.subtle.digest(
+    'SHA-256',
+    new TextEncoder().encode(String(content ?? '')),
+  );
+  return Array.from(
+    new Uint8Array(digest),
+    (byte) => byte.toString(16).padStart(2, '0'),
+  ).join('');
+}

package/src/domain/editable-text.js ADDED Viewed

@@ -0,0 +1,3 @@
+export function normalizeEditableText(content) {
+  return String(content ?? '').replace(/\r\n?/g, '\n');
+}

package/src/domain/exact-text-edits.js ADDED Viewed

@@ -0,0 +1,69 @@
+function createEditError(code, message) {
+  const error = new Error(message);
+  error.code = code;
+  return error;
+}
+export function validateExactTextReplacements(replacements, {
+  maxCharacters = Infinity,
+  maxReplacements = Infinity,
+} = {}) {
+  if (!Array.isArray(replacements) || replacements.length === 0) {
+    throw createEditError('EXACT_EDIT_REQUIRED', 'At least one text replacement is required');
+  }
+  if (replacements.length > maxReplacements) {
+    throw createEditError('EXACT_EDIT_LIMIT', `At most ${maxReplacements} text replacements are allowed`);
+  }
+  let characterCount = 0;
+  for (const replacement of replacements) {
+    if (
+      !replacement
+      || typeof replacement.oldText !== 'string'
+      || replacement.oldText.length === 0
+      || typeof replacement.newText !== 'string'
+    ) {
+      throw createEditError('EXACT_EDIT_INVALID', 'Each replacement requires non-empty oldText and string newText');
+    }
+    if (replacement.oldText === replacement.newText) {
+      throw createEditError('EXACT_EDIT_UNCHANGED', 'A replacement must change the document');
+    }
+    characterCount += replacement.oldText.length + replacement.newText.length;
+  }
+  if (characterCount > maxCharacters) {
+    throw createEditError('EXACT_EDIT_LIMIT', `Text replacements may contain at most ${maxCharacters} characters`);
+  }
+  return replacements;
+}
+export function resolveExactTextChanges(content, replacements, limits = {}) {
+  const text = String(content ?? '');
+  const validated = validateExactTextReplacements(replacements, limits);
+  const changes = validated.map(({ newText, oldText }) => {
+    const from = text.indexOf(oldText);
+    if (from < 0) {
+      throw createEditError('EXACT_EDIT_MISMATCH', 'A requested text replacement no longer matches the document');
+    }
+    if (text.includes(oldText, from + 1)) {
+      throw createEditError('EXACT_EDIT_NOT_UNIQUE', 'A requested text replacement is not unique in the document');
+    }
+    return { from, insert: newText, to: from + oldText.length };
+  }).sort((left, right) => left.from - right.from);
+  for (let index = 1; index < changes.length; index += 1) {
+    if (changes[index].from < changes[index - 1].to) {
+      throw createEditError('EXACT_EDIT_OVERLAP', 'Requested text replacements overlap');
+    }
+  }
+  return changes;
+}
+export function applyExactTextChanges(content, changes) {
+  let result = String(content ?? '');
+  for (let index = changes.length - 1; index >= 0; index -= 1) {
+    const change = changes[index];
+    result = result.slice(0, change.from) + change.insert + result.slice(change.to);
+  }
+  return result;
+}