openwriter 0.19.0 → 0.20.0

package/dist/server/mcp.js

@@ -14,7 +14,7 @@ import { getDocument, getWordCount, getPendingChangeCount, getTitle, getStatus,
 import { tiptapToBlocks } from './node-blocks.js';
 import { harvestSentenceHashes, harvestCharCount } from './enrichment.js';
 import { listDocuments, switchDocument, createDocument, createDocumentFile, deleteDocument, openFile, getActiveFilename, updateDocumentTitle, promoteTempFile, archiveDocument, unarchiveDocument, resolveDocId, filenameByDocId, searchDocuments, listDirtyDocs, crawlDocs, enrichmentFooter, buildEnrichmentInstructions } from './documents.js';
-import { extractForwardLinks } from './backlinks.js';
+import { readFrontmatter, writeFrontmatter, computeBacklinksFor, invalidateBacklinksCache } from './backlinks.js';
 import { logger, generateRequestId, withRequestId } from './logger.js';
 import { broadcastDocumentSwitched, broadcastDocumentsChanged, broadcastWorkspacesChanged, broadcastTitleChanged, broadcastMetadataChanged, broadcastPendingDocsChanged, broadcastWritingStarted, broadcastWritingFinished, broadcastCommentsChanged } from './ws.js';
 import { listWorkspaces, getWorkspace, getDocTitle, getItemContext, addDoc, updateWorkspaceContext, createWorkspace, deleteWorkspace, addContainerToWorkspace, findOrCreateWorkspace, findOrCreateContainer, moveDoc, moveContainer, reorderWorkspaceAfter, removeContainer, renameWorkspace, renameContainer, removeDocFromAllWorkspaces, findWorkspacesContainingDoc, collectFilesInWorkspace } from './workspaces.js';
@@ -567,6 +567,28 @@ export const TOOL_REGISTRY = [
                 if (!isAutoAcceptActive(filename || getActiveFilename(), getMetadata())) {
                     markAllNodesAsPending(doc, 'insert');
                 }
+                // Bug #1 fix (v0.20.0): preserve the stub's trailing canonical paragraph(s).
+                // updateDocument(doc) overwrites state.canonical wholesale — without this
+                // merge, the create_document → populate_document sequence loses the stub's
+                // auto-generated trailing paragraph from canonical. When the browser later
+                // accepts the inserts and sends a doc-update with its TipTap-rendered tree
+                // (which also has a trailing empty paragraph, but a different ID), the
+                // save-time matcher classifies the stub's original trailing as deleted →
+                // graveyard, while the freshly added inserts have no previousNodes match.
+                // Cascading state corruption observed in live test 2026-05-22.
+                const existingCanonical = getCanonical();
+                if (existingCanonical?.content?.length) {
+                    const incomingIds = new Set(doc.content
+                        .map((n) => n?.attrs?.id)
+                        .filter((id) => typeof id === 'string'));
+                    const preserved = existingCanonical.content.filter((n) => {
+                        const id = n?.attrs?.id;
+                        return id && !incomingIds.has(id);
+                    });
+                    if (preserved.length > 0) {
+                        doc.content = [...doc.content, ...preserved];
+                    }
+                }
                 updateDocument(doc);
                 updatePendingCacheForActiveDoc();
                 save();
@@ -1687,115 +1709,69 @@ export const TOOL_REGISTRY = [
     },
     {
         name: 'link_to',
-        description: 'Wrap anchor text in a source doc with a doc: link pointing at another doc. Operates in place on the block containing the anchor text — never creates a duplicate paragraph. Optionally target a specific paragraph (target_node_id) for paragraph-level navigation, with an optional quote for scroll-anchor fallback. The on-save backlinks pipeline then auto-updates the target doc\'s frontmatter `backlinks` field — so this single tool call creates both the forward link and the backlink. Use after writing prose to cross-reference concepts: agent writes about "territorial imperative" then calls link_to to point that phrase at the canonical concept doc.',
+        description: 'Declare a structural doc-to-doc connection. Writes target_doc_id into the source doc\'s `references:` frontmatter array. Body markdown is NEVER mutated — this is metadata, not prose. Idempotent: calling twice with the same source/target is a no-op. The inbound list on the target is computed live from the inverse of every doc\'s references — no stored derived field. v0.20.0 breaking change: dropped `text`, `target_node_id`, and `quote` parameters; connections are structural, not anchored to prose. Legacy prose `doc:` links continue to render and auto-populate `references` on save (backward compat).',
         schema: {
-            text: z.string().describe('Anchor text in the source doc to wrap with the link. Exact substring match. First UNLINKED occurrence wins — calling link_to N times with the same anchor wraps N distinct occurrences, skipping ones already linked to the same target.'),
-            source_doc_id: z.string().describe('Source document docId (8-char hex from list_documents). The doc containing the anchor text. NOT the active doc — must be explicit so user-driven navigation in the browser can\'t silently change the target.'),
-            target_doc_id: z.string().describe('Target document docId (8-char hex from list_documents or search_docs). The doc the link points AT.'),
-            target_node_id: z.string().optional().describe('Optional 8-char hex nodeId for paragraph-level targeting. When provided, clicking the link scrolls to that paragraph in the target doc.'),
-            quote: z.string().optional().describe('Optional text snippet for scroll-anchor fallback when target_node_id has drifted (e.g. paragraph was rewritten).'),
+            source_doc_id: z.string().describe('Source document docId (8-char hex from list_documents). The doc declaring the connection.'),
+            target_doc_id: z.string().describe('Target document docId (8-char hex from list_documents or search_docs). The doc the connection points AT.'),
         },
-        handler: async ({ text, source_doc_id, target_doc_id, target_node_id, quote }) => {
+        handler: async ({ source_doc_id, target_doc_id }) => {
             const sourceFilename = resolveDocId(source_doc_id);
             if (!sourceFilename) {
                 return { content: [{ type: 'text', text: `source_doc_id "${source_doc_id}" not found. Use list_documents to find the right docId.` }] };
             }
-            // Build the href in canonical doc:DOCID#NODEID?q=quote form so we can also
-            // detect "this text is already wrapped with THIS link" and skip it.
-            let href = `doc:${target_doc_id}`;
-            if (target_node_id)
-                href += `#${target_node_id}`;
-            if (quote)
-                href += `?q=${encodeURIComponent(quote)}`;
-            // Load the source doc — from in-memory state if it's active, from disk
-            // otherwise. Explicit source dispatch prevents the active-doc race where
-            // a user click in the browser silently changes which doc gets edited.
+            const targetFilename = resolveDocId(target_doc_id);
+            if (!targetFilename) {
+                return { content: [{ type: 'text', text: `target_doc_id "${target_doc_id}" not found. Use list_documents or search_docs to find the right docId.` }] };
+            }
+            if (source_doc_id === target_doc_id) {
+                return { content: [{ type: 'text', text: `Cannot link a document to itself (source_doc_id and target_doc_id are both "${source_doc_id}").` }] };
+            }
+            // Load source's current references (active doc → in-memory; otherwise → disk).
             const sourceIsActive = sourceFilename === getActiveFilename();
-            let sourceDoc;
+            let currentReferences;
             if (sourceIsActive) {
-                sourceDoc = getDocument();
+                const meta = getMetadata();
+                currentReferences = Array.isArray(meta?.references) ? [...meta.references] : [];
             }
             else {
-                const cached = getCachedDocument(resolveDocPath(sourceFilename));
-                if (cached) {
-                    sourceDoc = cached.document;
-                }
-                else {
-                    try {
-                        const raw = readFileSync(resolveDocPath(sourceFilename), 'utf-8');
-                        sourceDoc = markdownToTiptap(raw).document;
-                    }
-                    catch (err) {
-                        return { content: [{ type: 'text', text: `Failed to read source doc "${source_doc_id}": ${err.message}` }] };
-                    }
-                }
+                const fm = readFrontmatter(sourceFilename);
+                currentReferences = Array.isArray(fm?.data?.references) ? [...fm.data.references] : [];
             }
-            // Locate the first block containing the anchor text WHERE the text is
-            // not already entirely wrapped with a link to the same href. This makes
-            // link_to idempotent and lets repeat calls wrap successive occurrences.
-            let sourceNodeId = null;
-            let totalOccurrences = 0;
-            let alreadyLinkedOccurrences = 0;
-            function isTextAlreadyLinked(nodeContent) {
-                // Concatenate text from inline children that have a link mark matching href
-                let linkedText = '';
-                for (const child of nodeContent) {
-                    if (child.type !== 'text' || !child.text)
-                        continue;
-                    const marks = child.marks || [];
-                    const hasMatchingLink = marks.some((m) => m.type === 'link' && m.attrs?.href === href);
-                    if (hasMatchingLink)
-                        linkedText += child.text;
-                }
-                return linkedText.includes(text);
+            // Idempotent: target already declared → no-op.
+            if (currentReferences.includes(target_doc_id)) {
+                return { content: [{ type: 'text', text: JSON.stringify({
+                                success: true,
+                                sourceDocId: source_doc_id,
+                                targetDocId: target_doc_id,
+                                alreadyReferenced: true,
+                                references: currentReferences,
+                            }) }] };
             }
-            function walk(nodes) {
-                if (sourceNodeId)
-                    return;
-                for (const node of nodes) {
-                    if (sourceNodeId)
-                        return;
-                    if (Array.isArray(node.content)) {
-                        const blockText = node.content.map((c) => c.text || '').join('');
-                        if (node.attrs?.id && blockText.includes(text)) {
-                            totalOccurrences++;
-                            if (isTextAlreadyLinked(node.content)) {
-                                alreadyLinkedOccurrences++;
-                                walk(node.content);
-                                continue;
-                            }
-                            sourceNodeId = node.attrs.id;
-                            return;
-                        }
-                        walk(node.content);
-                    }
-                }
+            // Append + dedup via Set round-trip.
+            const newReferences = Array.from(new Set([...currentReferences, target_doc_id]));
+            if (sourceIsActive) {
+                // Active doc: mutate state.metadata and let save() persist the frontmatter.
+                // save()'s writeToDisk path invalidates the backlinks cache.
+                setMetadata({ references: newReferences });
+                save();
+                broadcastMetadataChanged(getMetadata());
             }
-            walk(sourceDoc.content);
-            if (!sourceNodeId) {
-                if (totalOccurrences > 0 && totalOccurrences === alreadyLinkedOccurrences) {
-                    return { content: [{ type: 'text', text: `Anchor text "${text}" found in source doc but all ${totalOccurrences} occurrence(s) are already linked to ${href}. Nothing to do.` }] };
+            else {
+                // Non-active doc: write frontmatter directly, preserving body verbatim.
+                const fm = readFrontmatter(sourceFilename);
+                if (!fm) {
+                    return { content: [{ type: 'text', text: `Failed to read source doc "${source_doc_id}" frontmatter.` }] };
                 }
-                return { content: [{ type: 'text', text: `Anchor text "${text}" not found in source doc "${source_doc_id}" (${sourceFilename}). Use search_docs or read_pad to verify.` }] };
-            }
-            // Apply the link mark in place. Dispatch by active vs non-active so the
-            // edit always lands in the right doc — never silently in whatever doc
-            // happens to be foregrounded in the browser.
-            const editResult = sourceIsActive
-                ? applyTextEdits(sourceNodeId, [{ find: text, addMark: { type: 'link', attrs: { href } } }])
-                : applyTextEditsToFile(sourceFilename, sourceNodeId, [{ find: text, addMark: { type: 'link', attrs: { href } } }]);
-            if (!editResult.success) {
-                return { content: [{ type: 'text', text: `Failed to apply link mark: ${editResult.error}` }] };
+                const merged = { ...fm.data, references: newReferences };
+                writeFrontmatter(sourceFilename, merged);
+                invalidateDocCache(resolveDocPath(sourceFilename));
+                invalidateBacklinksCache();
             }
-            if (sourceIsActive)
-                save(); // triggers writeToDisk → backlinks pipeline updates target's frontmatter
             return { content: [{ type: 'text', text: JSON.stringify({
                             success: true,
                             sourceDocId: source_doc_id,
-                            sourceFilename,
-                            nodeId: sourceNodeId,
-                            href,
-                            ...(totalOccurrences > 1 ? { remainingUnlinked: totalOccurrences - alreadyLinkedOccurrences - 1 } : {}),
+                            targetDocId: target_doc_id,
+                            references: newReferences,
                         }) }] };
         },
     },
@@ -1847,7 +1823,7 @@ export const TOOL_REGISTRY = [
     },
     {
         name: 'get_graph',
-        description: 'Return forward links + backlinks for a doc — the crawl primitive for cross-doc context retrieval. Forward links extracted from the doc body, backlinks read from the doc\'s frontmatter (maintained by the on-save backlinks pipeline). Optional depth walks neighbors recursively (cap 3).',
+        description: 'Return forward + inbound connections for a doc — the crawl primitive for cross-doc context retrieval. Forward connections read from the doc\'s `references:` frontmatter (structural data, v0.20). Inbound computed live by scanning every doc\'s references for entries pointing at this one (no stored derived field). Optional depth walks neighbors recursively (cap 3). v0.20.0 breaking change: edges are doc-to-doc; per-paragraph granularity (from_node/to_node/anchor text) was dropped — that was an artifact of the prose-link model.',
         schema: {
             docId: z.string().describe('Center docId for the graph walk (8-char hex).'),
             depth: z.number().optional().describe('Hops to walk outward (default 1, max 3). depth=1 returns just the center\'s links; depth=2 also includes neighbors\' links.'),
@@ -1867,28 +1843,18 @@ export const TOOL_REGISTRY = [
                 catch {
                     return;
                 }
-                const forward = extractForwardLinks(target.document, id);
-                const backlinks = Array.isArray(target.metadata.backlinks) ? target.metadata.backlinks : [];
+                const forward = Array.isArray(target.metadata.references) ? target.metadata.references : [];
+                const backlinks = computeBacklinksFor(id);
                 nodes.push({
                     docId: id,
                     title: target.title,
-                    forward: forward.map((l) => ({
-                        text: l.text,
-                        from_node: l.from_node,
-                        to_doc: l.to_doc,
-                        ...(l.to_node ? { to_node: l.to_node } : {}),
-                    })),
-                    backlinks: backlinks.map((b) => ({
-                        text: b.text,
-                        from_doc: b.from_doc,
-                        from_node: b.from_node,
-                        ...(b.to_node ? { to_node: b.to_node } : {}),
-                    })),
+                    forward: forward.map((to_doc) => ({ to_doc })),
+                    backlinks: backlinks.map((b) => ({ from_doc: b.from_doc })),
                 });
                 if (hopsLeft > 0) {
                     const neighbors = new Set();
-                    for (const l of forward)
-                        neighbors.add(l.to_doc);
+                    for (const to_doc of forward)
+                        neighbors.add(to_doc);
                     for (const b of backlinks)
                         neighbors.add(b.from_doc);
                     for (const n of neighbors) {

package/dist/server/state.js

@@ -10,7 +10,7 @@ import { tiptapToMarkdown, tiptapToMarkdownChecked, tiptapToBody, markdownToTipt
 import { applyTextEditsToNode } from './text-edit.js';
 import { getDataDir, TEMP_PREFIX, ensureDataDir, filePathForTitle, tempFilePath, generateNodeId, LEAF_BLOCK_TYPES, resolveDocPath, isExternalDoc, atomicWriteFileSync, canonicalizePath, canonicalizeIdentifier } from './helpers.js';
 import { snapshotIfNeeded, ensureDocId } from './versions.js';
-import { extractForwardLinks, extractForwardLinksFromDisk, updateBacklinksForSource } from './backlinks.js';
+import { syncReferencesFromProse, invalidateBacklinksCache, writeFrontmatter } from './backlinks.js';
 import { isAutoAcceptInheritedForDoc } from './workspaces.js';
 import { matchNodes } from './node-matcher.js';
 import { tiptapToBlocks, applyIdsToTiptap } from './node-blocks.js';
@@ -434,6 +434,15 @@ function stripLegacyAgentCreated(metadata) {
     if (metadata && 'agentCreated' in metadata)
         delete metadata.agentCreated;
 }
+/** Strip the legacy `backlinks` field. v0.19 stored derived inbound edges in
+ *  frontmatter; v0.20 computes them live from the inverse of `references`
+ *  across the workspace. Any save that visits a doc with the stale field drops
+ *  it — lazy migration. No data loss because the new `references` field on
+ *  source docs is the authoritative inbound source; we can always recompute. */
+function stripLegacyBacklinks(metadata) {
+    if (metadata && 'backlinks' in metadata)
+        delete metadata.backlinks;
+}
 function persistExternalDocs() {
     try {
         atomicWriteFileSync(getExternalDocsFile(), JSON.stringify([...externalDocs]));
@@ -1990,16 +1999,6 @@ function writeToDisk() {
         return;
     }
     ensureDataDir();
-    // Capture old forward links BEFORE we overwrite the file — needed by the
-    // backlinks engine to know which target docs to refresh when source changes.
-    // Skip for external docs (they don't participate in the doc graph).
-    let oldForwardLinks = [];
-    if (!isExternalDoc(state.filePath) && state.docId) {
-        try {
-            oldForwardLinks = extractForwardLinksFromDisk(state.filePath, state.docId);
-        }
-        catch { /* best-effort */ }
-    }
     // Stub graduation: once the doc contains accepted content, it's no longer
     // a fresh stub. Remove it from the in-memory stub registry so reject-all
     // can never trigger the cleanup-delete on it.
@@ -2009,8 +2008,10 @@ function writeToDisk() {
     }
     // Defensive: never serialize `agentCreated` to disk. The field is dead;
     // any code reading it would be the bug, not the field's presence.
-    if (state.metadata)
+    if (state.metadata) {
         stripLegacyAgentCreated(state.metadata);
+        stripLegacyBacklinks(state.metadata);
+    }
     let markdown;
     if (isExternalDoc(state.filePath)) {
         // External files: preserve original frontmatter verbatim, no OpenWriter metadata injected.
@@ -2204,16 +2205,27 @@ function writeToDisk() {
         snapshotIfNeeded(state.docId, state.filePath);
     }
     catch { /* ignore */ }
-    // Backlinks update: refresh target docs' backlinks frontmatter if source's
-    // forward links changed. Best-effort — never blocks the save it follows.
+    // Auto-sync references from prose: legacy `doc:` prose links still render
+    // (PadLink extension), but the graph/crawl/backlinks-panel read the
+    // structural `references:` field. After every save, scan the body for
+    // prose links and merge their targets into references — backward compat
+    // without forcing rewrites. Then invalidate the live-backlinks cache so
+    // the next /api/backlinks/:docId call sees the fresh inverse.
+    // Best-effort — never blocks the save it follows.
     if (!isExternalDoc(state.filePath) && state.docId) {
         try {
-            const newForwardLinks = extractForwardLinks(state.document, state.docId);
-            updateBacklinksForSource(state.docId, newForwardLinks, oldForwardLinks);
+            const sync = syncReferencesFromProse(state.docId, state.document, state.metadata || {});
+            if (sync && state.metadata) {
+                state.metadata.references = sync.newReferences;
+                // Second tiny write: re-persist frontmatter only (body already on disk).
+                const filename = state.filePath.split(/[/\\]/).pop() || '';
+                writeFrontmatter(filename, state.metadata);
+            }
         }
         catch (err) {
-            console.error('[State] backlinks update failed:', err);
+            console.error('[State] references auto-sync failed:', err);
         }
+        invalidateBacklinksCache();
     }
 }
 export function save() {
@@ -2756,6 +2768,28 @@ export function populateDocumentFile(filename, doc) {
     if (!isAutoAcceptActive(filename, parsed.metadata)) {
         markAllNodesAsPending(doc, 'insert');
     }
+    // Bug #1 fix (v0.20.0): preserve the stub's trailing canonical paragraph(s).
+    // flushDocToFile writes `doc` directly — it does NOT merge with the existing
+    // parsed.document on disk. Without this merge step, the stub's auto-generated
+    // trailing paragraph falls out of canonical, the matcher's `previousNodes`
+    // for any subsequent save no longer references it, and a follow-up Accept All
+    // doc-update can find itself with no matching previousNodes to anchor against.
+    // Cascading: the matcher classifies the newly accepted inserts as deletions
+    // (orphaned from the empty previousNodes set), they go to graveyard, the disk
+    // body ends up empty.
+    // Mirrors the active-doc fix in mcp.ts:populate_document.
+    if (parsed.document?.content?.length) {
+        const incomingIds = new Set(doc.content
+            .map((n) => n?.attrs?.id)
+            .filter((id) => typeof id === 'string'));
+        const preserved = parsed.document.content.filter((n) => {
+            const id = n?.attrs?.id;
+            return id && !incomingIds.has(id);
+        });
+        if (preserved.length > 0) {
+            doc.content = [...doc.content, ...preserved];
+        }
+    }
     flushDocToFile(filename, doc, parsed.title, parsed.metadata);
     const pendingCount = countPending(doc.content);
     const text = extractText(doc.content);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openwriter",
-  "version": "0.19.0",
+  "version": "0.20.0",
   "description": "The open-source writing surface for AI agents. Markdown-native editor with pending change review — your agent writes, you accept or reject.",
   "type": "module",
   "license": "MIT",