openwriter 0.25.0 → 0.27.0

package/dist/server/peek-outline.js

@@ -273,41 +273,108 @@ export function countWords(nodes) {
         return 0;
     return text.split(/\s+/).length;
 }
-/** Truncate a doc at a top-level node boundary so the returned content
- *  doesn't exceed `maxWords`. Returns the original doc unchanged if it
- *  already fits. Always includes at least one top-level node so callers
- *  never receive an empty body.
+/** Read a region of a doc, truncated at a top-level node boundary so the
+ *  returned content doesn't exceed `maxWords` (unless `force` is set).
  *
- *  read_pad's contract: a fixed-window read, not a full-body read. Above
- *  the cap, the agent gets the doc opening (most context-rich slice —
- *  title, intro, first few sections) plus the lastNodeId so `peek_doc`
- *  can continue from the boundary, or `outline_doc` / `search_docs` can
- *  jump elsewhere.
+ *  Three modes:
+ *  - **Default** (no slice, no force) — first N words of the doc, capped at
+ *    `maxWords`. read_pad's original contract: doc opening + continuation hint.
+ *  - **Slice** (`{ from, to }`) — words in the percentile range. Snaps to top-level
+ *    node boundaries so blocks aren't split mid-sentence. Still subject to
+ *    `maxWords` unless `force` is set; an agent walking 10% chunks of a large
+ *    doc gets predictable per-call cost.
+ *  - **Force** — bypass the cap. Returns the full requested region (whole doc
+ *    if no slice, the whole slice if sliced). Use for full-doc audits and
+ *    rewrites where the agent has explicitly accepted the cost.
  *
  *  Node-boundary truncation (never splits a top-level block) keeps the
  *  returned slice structurally valid markdown — list items, blockquotes,
  *  and code blocks stay intact. */
-export function truncateRead(doc, maxWords) {
+export function truncateRead(doc, options = {}) {
+    const maxWords = options.maxWords ?? 2000;
+    const force = !!options.force;
+    const sliceIn = options.slice ?? null;
+    // Clamp/validate slice — clamp to [0,1], silently fix swapped or degenerate inputs.
+    let slice = null;
+    if (sliceIn) {
+        const from = Math.max(0, Math.min(1, sliceIn.from));
+        const to = Math.max(0, Math.min(1, sliceIn.to));
+        slice = from < to ? { from, to } : { from: 0, to: 1 };
+    }
     const content = doc.content || [];
     const totalWords = countWords(content);
     const lastTopId = (n) => n?.attrs?.id ?? null;
-    if (totalWords <= maxWords) {
+    // Empty doc — nothing to slice or truncate.
+    if (content.length === 0) {
         return {
             doc,
             truncated: false,
+            totalWords: 0,
+            returnedWords: 0,
+            firstNodeId: null,
+            lastNodeId: null,
+            remaining: 0,
+            slice,
+            forced: force,
+        };
+    }
+    // Step 1: pick the candidate node range based on slice (or all nodes if no slice).
+    // Word-position-based: walk top-level nodes, snap to boundaries that contain
+    // the slice's word range. A node is included if any of its words fall inside
+    // [fromWord, toWord) — rounds outward, agent always gets whole blocks.
+    let candidateStart = 0;
+    let candidateEnd = content.length;
+    let candidateTotalWords = totalWords;
+    if (slice) {
+        const fromWord = Math.floor(slice.from * totalWords);
+        const toWord = Math.ceil(slice.to * totalWords);
+        let cum = 0;
+        let startIdx = -1;
+        let endIdx = content.length;
+        for (let i = 0; i < content.length; i++) {
+            const w = countWords([content[i]]);
+            const nodeStart = cum;
+            const nodeEnd = cum + w;
+            // Include node if its word span overlaps [fromWord, toWord).
+            if (startIdx === -1 && nodeEnd > fromWord)
+                startIdx = i;
+            if (startIdx !== -1 && nodeStart >= toWord) {
+                endIdx = i;
+                break;
+            }
+            cum += w;
+        }
+        if (startIdx === -1)
+            startIdx = content.length - 1;
+        candidateStart = startIdx;
+        candidateEnd = endIdx;
+        candidateTotalWords = countWords(content.slice(candidateStart, candidateEnd));
+    }
+    // Step 2: apply maxWords cap to the candidate range (unless forced).
+    const candidate = content.slice(candidateStart, candidateEnd);
+    if (force || candidateTotalWords <= maxWords) {
+        const firstNodeId = lastTopId(candidate[0]);
+        const lastNodeId = lastTopId(candidate[candidate.length - 1]);
+        return {
+            doc: { ...doc, content: candidate },
+            truncated: false,
             totalWords,
-            returnedWords: totalWords,
-            lastNodeId: lastTopId(content[content.length - 1]),
+            returnedWords: candidateTotalWords,
+            firstNodeId,
+            lastNodeId,
             remaining: 0,
+            slice,
+            forced: force,
         };
     }
+    // Step 3: candidate exceeds cap — truncate from the start of the candidate
+    // range, including whole top-level blocks until adding the next would exceed
+    // the cap. Always include at least one node.
     const included = [];
     let words = 0;
     let lastNodeId = null;
-    for (const n of content) {
+    for (const n of candidate) {
         const w = countWords([n]);
-        // Always include at least one node — even if it alone exceeds the cap,
-        // an empty body would be a worse failure mode than a slightly oversize one.
         if (included.length > 0 && words + w > maxWords)
             break;
         included.push(n);
@@ -320,8 +387,11 @@ export function truncateRead(doc, maxWords) {
         truncated: true,
         totalWords,
         returnedWords: words,
+        firstNodeId: lastTopId(included[0]),
         lastNodeId,
-        remaining: totalWords - words,
+        remaining: candidateTotalWords - words,
+        slice,
+        forced: false,
     };
 }
 /** Find blocks whose text matches the query inside one doc. Returns up to

package/dist/server/pending-metadata.js

@@ -0,0 +1,65 @@
+/**
+ * Pending metadata — sibling of pending-overlay.ts for frontmatter-level
+ * staging. Where the overlay holds proposed BLOCK changes (insert / rewrite
+ * / delete on TipTap nodes), this module holds proposed METADATA changes —
+ * for now just the document title.
+ *
+ * Architectural model:
+ *   - Pending metadata lives in the SAME sidecar file as the block overlay
+ *     (_pending/{docId}.json), under a top-level `metadata:` key. The
+ *     pending-overlay module owns the `entries:` key; this module owns the
+ *     `metadata:` key. Each preserves the other's slot when it writes.
+ *   - The canonical disk .md file's frontmatter is NEVER modified by a
+ *     pending stage — the title only changes on disk after the user accepts.
+ *     Reject discards the proposal; nothing on disk moves.
+ *   - The active document's pending metadata is mirrored into state.ts as
+ *     `state.pendingMetadata` so WS broadcasts and getters expose it without
+ *     a disk read on every poll.
+ *
+ * Why a separate module from pending-overlay.ts:
+ *   - The overlay model is keyed by nodeId and assumes a TipTap tree. Title
+ *     is not in the tree — it's a YAML frontmatter field. Forcing it into a
+ *     fake "node" would corrupt the overlay invariants (nodeId stability,
+ *     splitMergedDoc tree-walk, applyOverlayPure idempotency).
+ *   - Future metadata-staging (tags, status, custom frontmatter fields) lands
+ *     here without further churn to the overlay code path.
+ *
+ * Scope (phase 1): document title only. tag_doc / untag_doc / set_metadata
+ * for non-title fields / mark_enriched still write hot. Workspace and
+ * container renames also still write hot — they live in workspace manifests,
+ * not per-doc sidecars, and need a separate decision.
+ *
+ * adr: adr/pending-overlay-model.md
+ */
+import { readSidecarRaw, writeSidecarRaw } from './pending-overlay.js';
+import { logger } from './logger.js';
+// ============================================================================
+// SIDECAR I/O
+// ============================================================================
+/** Read the pending-metadata slot from the per-doc sidecar. Returns null if
+ *  the sidecar is missing or has no metadata slot. */
+export function loadPendingMetadata(docId) {
+    if (!docId)
+        return null;
+    const raw = readSidecarRaw(docId);
+    if (!raw?.metadata || Object.keys(raw.metadata).length === 0)
+        return null;
+    return raw.metadata;
+}
+/** Persist the pending-metadata slot. Preserves the sidecar's existing
+ *  `entries:` slot. Passing null (or an empty object) clears the metadata
+ *  and may delete the sidecar entirely if entries are also empty. */
+export function savePendingMetadata(docId, meta) {
+    if (!docId)
+        return;
+    const raw = readSidecarRaw(docId);
+    const entries = Array.isArray(raw?.entries) ? raw.entries : [];
+    const cleaned = meta && Object.keys(meta).length > 0 ? meta : null;
+    writeSidecarRaw(docId, { entries, metadata: cleaned || undefined });
+    if (cleaned?.title) {
+        logger.info('overlay', 'meta-stage', `docId=${docId} field=title from="${cleaned.title.from}" to="${cleaned.title.to}"`);
+    }
+    else {
+        logger.info('overlay', 'meta-clear', `docId=${docId}`);
+    }
+}

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,
             };
         }