openwriter 0.26.0 → 0.27.1

package/dist/server/pending-overlay.js

@@ -33,7 +33,8 @@
  */
 import { existsSync, mkdirSync, readFileSync, unlinkSync, readdirSync, rmSync } from 'fs';
 import { join } from 'path';
-import { getDataDir, atomicWriteFileSync } from './helpers.js';
+import { getDataDir, atomicWriteFileSync, resolveDocPath } from './helpers.js';
+import { markdownToTiptap } from './markdown-parse.js';
 // ============================================================================
 // DIAGNOSTIC HELPERS — node-text preview + entry summary for log readability
 // ============================================================================
@@ -107,6 +108,52 @@ export function loadOverlay(docId) {
         return [];
     }
 }
+/**
+ * Read the entire sidecar JSON object (raw). Used by pending-metadata.ts so
+ * it can read the `metadata:` slot without re-implementing file I/O. Returns
+ * null when the sidecar is missing or unreadable.
+ */
+export function readSidecarRaw(docId) {
+    if (!docId)
+        return null;
+    const path = getSidecarPath(docId);
+    if (!existsSync(path))
+        return null;
+    try {
+        const raw = readFileSync(path, 'utf-8');
+        return JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Atomically write the sidecar with the full JSON object. Both pending-overlay
+ * (entries) and pending-metadata (metadata slot) share this single file, so
+ * each must preserve the other's slot on every write. This is the low-level
+ * primitive both use.
+ *
+ * If the resulting object has no entries AND no metadata, the sidecar is
+ * deleted (absence = "nothing pending for this doc").
+ */
+export function writeSidecarRaw(docId, payload) {
+    if (!docId)
+        return;
+    const hasEntries = Array.isArray(payload.entries) && payload.entries.length > 0;
+    const hasMeta = !!payload.metadata && Object.keys(payload.metadata).length > 0;
+    if (!hasEntries && !hasMeta) {
+        deleteOverlay(docId);
+        return;
+    }
+    ensurePendingDir();
+    const path = getSidecarPath(docId);
+    const out = { version: 1 };
+    if (hasEntries)
+        out.entries = payload.entries;
+    if (hasMeta)
+        out.metadata = payload.metadata;
+    atomicWriteFileSync(path, JSON.stringify(out, null, 2));
+}
 export function saveOverlay(docId, entries) {
     if (!docId)
         return;
@@ -156,7 +203,22 @@ export function saveOverlay(docId, entries) {
         if (!newById.has(e.nodeId))
             changes.push(`-${entrySummary(e)}`);
     }
+    // Preserve the sidecar's `metadata` slot (used by pending-metadata.ts) across
+    // entries-only writes. Without this read-modify-write, saving entries would
+    // clobber any pending title-rename staged for the same doc.
+    // adr: adr/pending-overlay-model.md
+    const prevRaw = readSidecarRaw(docId);
+    const prevMetadata = prevRaw?.metadata && Object.keys(prevRaw.metadata).length > 0 ? prevRaw.metadata : null;
     if (dedupedEntries.length === 0) {
+        if (prevMetadata) {
+            // Entries empty but metadata still pending — keep the sidecar alive with
+            // metadata only.
+            writeSidecarRaw(docId, { metadata: prevMetadata });
+            if (prevEntries.length > 0) {
+                diagLog(`[Overlay] SAVE docId=${docId} entries=0 (was ${prevEntries.length}) metadata preserved`);
+            }
+            return;
+        }
         if (prevEntries.length > 0) {
             diagLog(`[Overlay] SAVE docId=${docId} → DELETE (was ${prevEntries.length} entries)`);
         }
@@ -165,7 +227,10 @@ export function saveOverlay(docId, entries) {
     }
     ensurePendingDir();
     const path = getSidecarPath(docId);
-    atomicWriteFileSync(path, JSON.stringify({ version: 1, entries: dedupedEntries }, null, 2));
+    const out = { version: 1, entries: dedupedEntries };
+    if (prevMetadata)
+        out.metadata = prevMetadata;
+    atomicWriteFileSync(path, JSON.stringify(out, null, 2));
     if (changes.length > 0) {
         diagLog(`[Overlay] SAVE docId=${docId} entries=${dedupedEntries.length} changes=[${changes.join(' | ')}]`);
     }
@@ -558,6 +623,24 @@ export function applyOverlay(canonical, entries) {
  * adr: adr/pending-overlay-model.md
  */
 export function applyOverlayPure(canonical, entries) {
+    // Strip the parser-fallback / createDocumentFile-stub empty paragraph
+    // before merging. markdownToTiptap mints a placeholder empty paragraph
+    // whenever the disk body has no block content (TipTap requires at least
+    // one node), and createDocumentFile mints the same shape for fresh empty
+    // docs. Both surface as a trailing empty `[p:...]` in the merged view
+    // whenever the doc's real content lives only in the overlay. We strip
+    // ONLY when canonical is exactly that single empty-paragraph shape AND
+    // no overlay entry anchors to it — so steady-state docs with real
+    // canonical content (or where an overlay entry references the empty
+    // paragraph deliberately, like a pending-delete on a user-emptied node)
+    // are untouched. adr: adr/pending-overlay-model.md
+    if (entries.length > 0 && isFallbackEmptyCanonical(canonical)) {
+        const fallbackId = canonical.content[0]?.attrs?.id;
+        const referenced = entries.some((e) => e.nodeId === fallbackId || e.afterNodeId === fallbackId || e.parentNodeId === fallbackId);
+        if (!referenced) {
+            canonical = { ...canonical, content: [] };
+        }
+    }
     const merged = canonical ? JSON.parse(JSON.stringify(canonical)) : { type: 'doc', content: [] };
     if (entries.length === 0)
         return merged;
@@ -860,3 +943,69 @@ export function migrateLegacyPending(doc, legacyPending) {
     walk(doc?.content || [], null);
     return entries;
 }
+// ============================================================================
+// MERGED-VIEW DOC LOADER
+// ============================================================================
+/**
+ * Load a doc from disk WITH its sidecar overlay applied — returns the
+ * user-visible merged view. This is the canonical reader for any code path
+ * that surfaces a non-active doc to the user (MCP read tools, browser HTTP
+ * fetches, anything that says "give me the doc").
+ *
+ * Why this exists. fb666e6 (May 2026) split persistence into two surfaces:
+ * the .md body holds canonical content, the per-docId sidecar at
+ * `_pending/{docId}.json` holds the pending overlay. Writes were updated
+ * to handle both halves symmetrically; reads weren't. The bare
+ * `markdownToTiptap` returns canonical-only — anyone calling it directly
+ * and treating the result as "the doc" silently drops the user's pending
+ * content. This function closes that asymmetry: there is one entry point
+ * for "load the doc," and it always materializes the full merged view.
+ *
+ * Callers that explicitly want canonical-only (the save-time matcher, the
+ * on-disk identity persistence path, sync-check roundtripping) continue to
+ * call `markdownToTiptap` directly. Those callsites are internal to the
+ * persistence layer and deliberately operate on the pre-overlay shape.
+ *
+ * Throws if the file doesn't exist (matches resolveDocTarget's existing
+ * behavior; callers that want soft-failure should check existsSync first).
+ *
+ * adr: adr/pending-overlay-model.md
+ */
+export function loadDocFromDisk(filename) {
+    const targetPath = resolveDocPath(filename);
+    if (!existsSync(targetPath)) {
+        throw new Error(`Document file not found: ${filename}`);
+    }
+    const raw = readFileSync(targetPath, 'utf-8');
+    const parsed = markdownToTiptap(raw);
+    const docId = (parsed.metadata && typeof parsed.metadata.docId === 'string')
+        ? parsed.metadata.docId
+        : '';
+    let document = parsed.document;
+    if (docId) {
+        const overlayEntries = loadOverlay(docId);
+        if (overlayEntries.length > 0) {
+            // applyOverlayPure handles the parser-fallback / stub-empty strip
+            // itself — see the comment block at its top for why.
+            document = applyOverlayPure(parsed.document, overlayEntries);
+        }
+    }
+    return {
+        document,
+        title: parsed.title,
+        metadata: parsed.metadata,
+        docId,
+        rawFrontmatter: parsed.rawFrontmatter,
+    };
+}
+/** True when a parsed doc's canonical body is `[{ paragraph with no content }]`
+ *  — the markdownToTiptap fallback shape that signals "disk body had no
+ *  block-level content." Genuine user empty paragraphs in a doc with other
+ *  real content don't trip this (length check is strict); only the parser
+ *  fallback's single-node case matches. */
+function isFallbackEmptyCanonical(canonical) {
+    if (!canonical?.content || canonical.content.length !== 1)
+        return false;
+    const node = canonical.content[0];
+    return node?.type === 'paragraph' && (!node.content || node.content.length === 0);
+}

package/dist/server/plugin-manager.js

@@ -146,12 +146,27 @@ export class PluginManager {
         }
         return resolved;
     }
-    /** Persist enabled/config state to ~/.openwriter/config.json. */
+    /**
+     * Persist enabled/config state to ~/.openwriter/config.json.
+     *
+     * IMPORTANT: plugins can store arbitrary nested data on their own slot
+     * (e.g. the github plugin stores `blogSites: [...]`). This writer
+     * preserves any such keys by merging into the existing on-disk slot
+     * rather than rebuilding the slot from scratch. Without this preserve
+     * step, every plugin enable/disable/config edit would silently drop
+     * blogSites and any other plugin-owned data.
+     *
+     * adr: adr/plugin-slot-nested-data.md
+     */
     savePluginState() {
-        const pluginsState = {};
+        const current = readConfig();
+        const existing = (current.plugins || {});
+        const pluginsState = { ...existing };
         for (const [name, managed] of this.plugins) {
+            const prior = (existing[name] || {});
             pluginsState[name] = {
-                enabled: managed.enabled,
+                ...prior, // preserve blogSites + any other plugin-owned data
+                enabled: managed.enabled, // overwrite managed fields
                 config: managed.config,
             };
         }

package/dist/server/state.js

@@ -16,7 +16,8 @@ import { matchNodes } from './node-matcher.js';
 import { tiptapToBlocks, applyIdsToTiptap } from './node-blocks.js';
 import { anyLegacyRaw } from './node-fingerprint.js';
 import { markdownToNodes, resolvePreviousNodes, resolveGraveyard } from './markdown-parse.js';
-import { extractOverlay, applyOverlayPure, splitMergedDoc, saveOverlay, loadOverlay, deleteOverlay, repairOverlaysOnStartup, diagLog } from './pending-overlay.js';
+import { extractOverlay, applyOverlayPure, splitMergedDoc, saveOverlay, loadOverlay, loadDocFromDisk, deleteOverlay, repairOverlaysOnStartup, diagLog } from './pending-overlay.js';
+import { loadPendingMetadata, savePendingMetadata } from './pending-metadata.js';
 import { harvestSentenceHashes, harvestCharCount, isEnrichmentStale } from './enrichment.js';
 import { clearActivityBuffer } from './activity-log.js';
 import { titleFromDoc, shouldAutoTitle } from './title-from-body.js';
@@ -84,6 +85,7 @@ const DEFAULT_DOC = {
 let state = {
     canonical: DEFAULT_DOC,
     overlay: new Map(),
+    pendingMetadata: null,
     document: DEFAULT_DOC,
     title: 'Untitled',
     metadata: { title: 'Untitled' },
@@ -543,6 +545,21 @@ export function getOverlay() {
 export function getTitle() {
     return state.title;
 }
+/** Snapshot of the active doc's pending metadata (title, etc.). Null if no
+ *  metadata is staged. The sidebar / title bar / ReviewTab consult this to
+ *  decide whether to render a metadata-pending decoration.
+ *  adr: adr/pending-overlay-model.md */
+export function getPendingMetadata() {
+    return state.pendingMetadata ? { ...state.pendingMetadata } : null;
+}
+/** Replace the active doc's pending metadata. Persists to the sidecar so the
+ *  proposal survives a doc switch or restart. Pass null to clear. */
+export function setPendingMetadata(meta) {
+    state.pendingMetadata = meta && Object.keys(meta).length > 0 ? meta : null;
+    if (state.docId) {
+        savePendingMetadata(state.docId, state.pendingMetadata);
+    }
+}
 export function getFilePath() {
     return state.filePath;
 }
@@ -775,6 +792,13 @@ export function setMetadata(updates) {
     state.metadata = merged;
     if (updates.title)
         state.title = updates.title;
+    // Same contract as updateDocument: any path that mutates persistent state
+    // MUST bump docVersion, otherwise writeToDisk's no-op gate
+    // (docVersion === lastSavedDocVersion) silently drops the write and the
+    // mutation never reaches disk. Metadata-only changes (mark-sent tweetUrl,
+    // schedule edits, autoAccept toggle) all flow through here.
+    // adr: adr/pending-overlay-model.md
+    bumpDocVersion();
     // Auto-tag based on context metadata
     const filename = state.filePath
         ? (isExternalDoc(state.filePath) ? state.filePath : state.filePath.split(/[/\\]/).pop() || '')
@@ -1026,11 +1050,19 @@ export function cancelDebouncedSave() {
     }
 }
 export function applyChanges(changes) {
-    // Apply to server-side document (source of truth)
-    const processed = applyChangesToDocument(changes);
-    // Bump version + lock browser doc-updates to prevent stale state overwrite
+    // Bump version BEFORE applying so new overlay entries created by
+    // applyChangesToDocument's setPrimaryFromMerged → setOverlayFromEntries
+    // pass are stamped with the post-bump version (the version we're about
+    // to broadcast), not the pre-bump version. Without this, a stale
+    // browser doc-update arriving with browserVersion == preBump satisfies
+    // syncBrowserDocUpdate's `addedAtVersion > browserVersion` filter as
+    // FALSE for entries just added by this call — preservedServerEntries
+    // becomes 0, the overlay is wiped, and the agent's write silently
+    // vanishes despite a success response. adr: adr/pending-overlay-model.md
     const version = bumpDocVersion();
     setAgentLockActive();
+    // Apply to server-side document (source of truth)
+    const processed = applyChangesToDocument(changes);
     // Broadcast processed changes (with server-assigned IDs + version) to browser clients
     for (const listener of listeners) {
         listener(processed, version);
@@ -1466,6 +1498,9 @@ export function setActiveDocument(doc, title, filePath, isTemp, lastModified, me
     // Pending overlay rehydration. See mergeOverlayOnLoad for the three cases
     // (sidecar present, legacy migration, no pending).
     mergeOverlayOnLoad();
+    // Pending metadata rehydration. Read the sidecar's `metadata:` slot so a
+    // staged title rename survives doc-switch and restart. adr: adr/pending-overlay-model.md
+    state.pendingMetadata = state.docId ? loadPendingMetadata(state.docId) : null;
     // Subscribe the fs watcher to this doc so external writes (Edit tool,
     // VSCode, scripts) trigger a unified reload + version bump + broadcast.
     // adr: adr/active-doc-watcher.md
@@ -1649,6 +1684,7 @@ export function clearAllCaches() {
     state = {
         canonical: DEFAULT_DOC,
         overlay: new Map(),
+        pendingMetadata: null,
         document: DEFAULT_DOC,
         title: 'Untitled',
         metadata: { title: 'Untitled' },
@@ -1750,6 +1786,12 @@ export function reloadActiveDocFromDisk() {
     // sidecar (or legacy migration). Recompute merged via the helper.
     state.canonical = canonical;
     setOverlayFromEntries(entries);
+    // Pending metadata rehydration — mirror what setActiveDocument does.
+    // External-write reloads must keep state.pendingMetadata aligned with the
+    // sidecar's metadata: slot, otherwise a staged title rename gets dropped
+    // from in-memory state the moment fs.watch fires.
+    // adr: adr/pending-overlay-model.md
+    state.pendingMetadata = state.docId ? loadPendingMetadata(state.docId) : null;
     // External writes change the body but leave disk frontmatter pointing at
     // the previous save's fingerprints. If the user cuts/deletes a block before
     // the next browser-driven save, the matcher graveyards with that stale
@@ -2355,6 +2397,12 @@ export function load() {
             // source.
             // adr: adr/pending-overlay-model.md
             mergeOverlayOnLoad();
+            // Pending metadata rehydration. Boot path bypasses setActiveDocument,
+            // so the per-doc sidecar's `metadata:` slot must be loaded here too.
+            // Without this, a server restart drops staged title renames from
+            // in-memory state until the user switches docs.
+            // adr: adr/pending-overlay-model.md
+            state.pendingMetadata = state.docId ? loadPendingMetadata(state.docId) : null;
             break;
         }
         catch {
@@ -2545,11 +2593,25 @@ export function addDocTag(filename, tag) {
         if (!tags.includes(tag)) {
             tags.push(tag);
             state.metadata.tags = tags;
-            // Preserve mtime — tag changes shouldn't affect sidebar sort order
+            // Same docVersion contract as setMetadata: tag changes mutate
+            // state.metadata, so they must bump or writeToDisk's no-op gate
+            // silently drops the write.
+            bumpDocVersion();
+            // Preserve mtime — tag changes shouldn't affect sidebar sort order.
+            // After rolling back disk mtime, we MUST also roll back state.loadedMtime
+            // (which writeToDisk just stamped to the post-write disk mtime).
+            // The fs.watch self-suppression contract is `diskMtime === loadedMtime`;
+            // a divergence here will fire a phantom "external write detected"
+            // reload banner when the watcher's debounced handler runs.
             const mtime = state.filePath ? safeGetMtime(state.filePath) : null;
             save();
-            if (mtime && state.filePath)
+            if (mtime && state.filePath) {
                 safeRestoreMtime(state.filePath, mtime);
+                try {
+                    state.loadedMtime = statSync(state.filePath).mtimeMs;
+                }
+                catch { /* best-effort */ }
+            }
         }
     }
     else {
@@ -2585,11 +2647,19 @@ export function removeDocTag(filename, tag) {
         if (idx >= 0) {
             tags.splice(idx, 1);
             state.metadata.tags = tags.length > 0 ? tags : undefined;
-            // Preserve mtime — tag changes shouldn't affect sidebar sort order
+            // Same docVersion contract as addDocTag — mutation must bump or
+            // writeToDisk's no-op gate silently drops the write.
+            bumpDocVersion();
+            // Same loadedMtime re-stamp as addDocTag — see comment there.
             const mtime = state.filePath ? safeGetMtime(state.filePath) : null;
             save();
-            if (mtime && state.filePath)
+            if (mtime && state.filePath) {
                 safeRestoreMtime(state.filePath, mtime);
+                try {
+                    state.loadedMtime = statSync(state.filePath).mtimeMs;
+                }
+                catch { /* best-effort */ }
+            }
         }
     }
     else {
@@ -2897,41 +2967,50 @@ function flushDocToFile(filename, doc, title, metadata) {
     invalidateBacklinksCache();
 }
 export function populateDocumentFile(filename, doc) {
-    const targetPath = resolveDocPath(filename);
-    const raw = readFileSync(targetPath, 'utf-8');
-    const parsed = markdownToTiptap(raw);
+    // Read the existing doc as the user-visible MERGED view — canonical body
+    // plus any pre-existing sidecar overlay. Using the bare markdownToTiptap
+    // here would silently drop pre-existing pending entries (the file's
+    // sidecar lives outside the .md body), so a re-populate or a populate on
+    // a doc with prior pending state would clobber the overlay on the
+    // subsequent flushDocToFile. adr: adr/pending-overlay-model.md
+    const loaded = loadDocFromDisk(filename);
     // Skip pending tagging when the target doc effectively has autoAccept on —
     // content commits directly as accepted.
-    if (!isAutoAcceptActive(filename, parsed.metadata)) {
+    if (!isAutoAcceptActive(filename, loaded.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) {
+    // Preserve any pre-existing real content (pending nodes from a prior
+    // populate or write) that isn't in the incoming set — so a re-populate or
+    // populate-on-top doesn't clobber prior agent proposals. flushDocToFile
+    // writes `doc` directly and extracts its overlay wholesale, so what isn't
+    // in `doc.content` after this step disappears from the next save.
+    //
+    // Empty paragraphs are explicitly NOT preserved. createDocumentFile mints
+    // a trailing empty paragraph as a TipTap "doc must have at least one
+    // node" stub; that stub is obsolete the moment populate provides real
+    // content, and preserving it leaves a phantom empty paragraph at the end
+    // of every populated doc forever. Mirrors the active-doc preserve in
+    // mcp.ts:populate_document. adr: adr/pending-overlay-model.md
+    if (loaded.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 preserved = loaded.document.content.filter((n) => {
             const id = n?.attrs?.id;
-            return id && !incomingIds.has(id);
+            if (!id || incomingIds.has(id))
+                return false;
+            const isEmptyParagraph = n.type === 'paragraph' && (!n.content || n.content.length === 0);
+            return !isEmptyParagraph;
         });
         if (preserved.length > 0) {
             doc.content = [...doc.content, ...preserved];
         }
     }
-    flushDocToFile(filename, doc, parsed.title, parsed.metadata);
+    flushDocToFile(filename, doc, loaded.title, loaded.metadata);
     const pendingCount = countPending(doc.content);
     const text = extractText(doc.content);
     const wordCount = text.trim() ? text.trim().split(/\s+/).length : 0;
-    return { title: parsed.title, wordCount, pendingCount };
+    return { title: loaded.title, wordCount, pendingCount };
 }
 /**
  * Apply node changes to a non-active document file on disk.
@@ -2954,12 +3033,17 @@ export function applyChangesToFile(filename, changes) {
         isTemp = cached.isTemp;
     }
     else {
-        const raw = readFileSync(targetPath, 'utf-8');
-        const parsed = markdownToTiptap(raw);
-        doc = parsed.document;
-        title = parsed.title;
-        metadata = parsed.metadata;
-        docId = metadata.docId || '';
+        // Cache miss — load the MERGED view (canonical + sidecar overlay). The
+        // bare markdownToTiptap would give canonical-only, so pre-existing pending
+        // entries would not be in `doc` when we apply the new changes. The
+        // subsequent flushDocToFile then extracts the overlay from `doc` and
+        // overwrites the sidecar — silently dropping every prior pending entry.
+        // adr: adr/pending-overlay-model.md
+        const loaded = loadDocFromDisk(filename);
+        doc = loaded.document;
+        title = loaded.title;
+        metadata = loaded.metadata;
+        docId = loaded.docId;
         isTemp = false;
     }
     const autoAccept = isAutoAcceptActive(filename, metadata);
@@ -3003,12 +3087,15 @@ export function applyTextEditsToFile(filename, nodeId, edits) {
         isTemp = cached.isTemp;
     }
     else {
-        const raw = readFileSync(targetPath, 'utf-8');
-        const parsed = markdownToTiptap(raw);
-        doc = parsed.document;
-        title = parsed.title;
-        metadata = parsed.metadata;
-        docId = metadata.docId || '';
+        // Cache miss — load the merged view so a target node living in the
+        // sidecar overlay (a pending insert the agent is now text-editing) is
+        // findable. Bare markdownToTiptap would only show canonical, and the
+        // findNode call below would fail. adr: adr/pending-overlay-model.md
+        const loaded = loadDocFromDisk(filename);
+        doc = loaded.document;
+        title = loaded.title;
+        metadata = loaded.metadata;
+        docId = loaded.docId;
         isTemp = false;
     }
     const found = findNode(doc.content, nodeId, doc.content);