@rarusoft/dendrite-wiki 0.1.0-alpha.0

package/dist/chart-prompts.js

@@ -0,0 +1,414 @@
+/**
+ * Per-chart-kind prompt templates for Mermaid diagram synthesis.
+ *
+ * M4 of the AI-mermaid-charts roadmap. The operator-side modal in M5 will
+ * call `POST /__review-bridge/synthesize/chart`, which calls a local
+ * Ollama model with a prompt built from these templates plus the
+ * surrounding page content. The model returns Mermaid source which the
+ * heuristic validator in `chart-insert.ts` accepts or rejects.
+ *
+ * Design notes:
+ *   - Each template is small. Local models (especially 3B–8B) have short
+ *     effective context windows in practice; long preambles hurt output
+ *     quality and increase latency. Each prompt is ~200 tokens of
+ *     instructions + the page content.
+ *   - Each template includes ONE concrete example of valid Mermaid for
+ *     that kind. Few-shot prompting works well for diagram syntax.
+ *   - Each template ends with an explicit "Output ONLY the Mermaid
+ *     source. Do not wrap in code fences. Do not explain." instruction.
+ *     We still tolerate fences in the response (the parser strips them)
+ *     but telling the model not to produce them gives cleaner output.
+ *   - The "context" provided to the model is intentionally just the
+ *     section the operator's cursor is in, not the whole page. Local
+ *     models do better with focused input — the modal in M5 enforces
+ *     this by default.
+ */
+export function buildChartPrompt(input) {
+    const template = TEMPLATES[input.kind];
+    const intentLine = input.intent?.trim()
+        ? `What the diagram should illustrate: ${input.intent.trim()}\n\n`
+        : '';
+    return `${template.instructions}
+
+${intentLine}Source content to draw from:
+"""
+${input.context.trim()}
+"""
+
+Output ONLY the Mermaid source. Do not wrap in code fences. Do not explain. Begin with "${template.firstWord}".`;
+}
+// Each template's `instructions` field is a short paragraph + one valid
+// example. The example is what makes the difference between "model knows
+// the syntax abstractly" and "model produces correct output." Keep
+// examples minimal — 4-6 nodes/edges max — so the model focuses on
+// SHAPE rather than imitating example content.
+const TEMPLATES = {
+    flowchart: {
+        firstWord: 'flowchart',
+        instructions: `You produce Mermaid flowchart diagrams. A flowchart shows steps and decisions in a process. Use the source content below to identify the steps and the order they happen in. Use [rectangles] for steps and {curly braces} for yes/no decisions. Label arrows with the condition or action that triggers them.
+
+CRITICAL FORMATTING RULES:
+- Put the header ("flowchart TD" or "flowchart LR") on its OWN LINE.
+- Put EACH node and EACH edge on its OWN LINE.
+- Do NOT use semicolons (;) to separate statements. Mermaid requires NEWLINES.
+- Indent each statement two spaces under the header.
+
+Example of valid Mermaid flowchart syntax:
+
+flowchart TD
+  A[Read request] --> B{Cache hit?}
+  B -->|yes| C[Return cached]
+  B -->|no| D[Fetch from DB]
+  D --> E[Update cache]
+  E --> C`
+    },
+    sequence: {
+        firstWord: 'sequenceDiagram',
+        instructions: `You produce Mermaid sequence diagrams. A sequence diagram shows messages flowing between participants over time, top to bottom. Use the source content below to identify the actors and the messages they send. Use --> for synchronous calls, -->> for responses, and -.- for asynchronous notifications.
+
+Example of valid Mermaid sequenceDiagram syntax:
+
+sequenceDiagram
+  participant Client
+  participant API
+  participant DB
+  Client->>API: POST /save
+  API->>DB: INSERT
+  DB-->>API: ok
+  API-->>Client: 200 OK`
+    },
+    state: {
+        firstWord: 'stateDiagram-v2',
+        instructions: `You produce Mermaid state diagrams. A state diagram shows the lifecycle of a single entity — what states it can be in and what transitions move it between them. Use [*] for the initial and final pseudo-states. Label transitions with the event or condition that triggers them.
+
+Example of valid Mermaid stateDiagram-v2 syntax:
+
+stateDiagram-v2
+  [*] --> Idle
+  Idle --> Running : start
+  Running --> Paused : pause
+  Paused --> Running : resume
+  Running --> [*] : finish`
+    },
+    class: {
+        firstWord: 'classDiagram',
+        instructions: `You produce Mermaid class diagrams. A class diagram shows the structure of a domain — classes (or types), their fields and methods, and the relationships between them. Use the source content below to identify the entities and their relationships.
+
+Example of valid Mermaid classDiagram syntax:
+
+classDiagram
+  class Order {
+    +String id
+    +Date createdAt
+    +submit()
+  }
+  class Customer {
+    +String email
+    +place(Order)
+  }
+  Customer "1" --> "*" Order : places`
+    },
+    er: {
+        firstWord: 'erDiagram',
+        instructions: `You produce Mermaid entity-relationship diagrams. An ER diagram shows database entities (tables/collections), their fields, and the relationships between them. Use the source content below to identify the entities and how they connect.
+
+Example of valid Mermaid erDiagram syntax:
+
+erDiagram
+  USER ||--o{ ORDER : places
+  ORDER ||--|{ LINE_ITEM : contains
+  USER {
+    string id PK
+    string email
+  }
+  ORDER {
+    string id PK
+    string user_id FK
+    date created_at
+  }`
+    },
+    gantt: {
+        firstWord: 'gantt',
+        instructions: `You produce Mermaid gantt charts. A gantt chart shows tasks scheduled over time. Use the source content below to identify the tasks, their durations, and any dependencies. Group related tasks under "section" headers.
+
+Example of valid Mermaid gantt syntax:
+
+gantt
+  title Project plan
+  dateFormat YYYY-MM-DD
+  section Design
+  Wireframes      :a1, 2026-01-01, 5d
+  Visual design   :a2, after a1, 7d
+  section Build
+  Backend         :b1, 2026-01-08, 14d
+  Frontend        :b2, after a2, 12d`
+    }
+};
+/**
+ * Strip Mermaid code fences from a model response if present. Models
+ * sometimes wrap their output in ```mermaid ... ``` despite being told not
+ * to; we accept both shapes. Also trims any prose before the diagram-type
+ * keyword (e.g., "Here's the diagram:\n\nflowchart TD..." → "flowchart TD...").
+ *
+ * Final pass: `normalizeMermaidLayout` repairs the common small-model
+ * failure mode of producing the entire diagram on a single line with `;`
+ * as statement separator (which Mermaid does NOT accept — it requires
+ * newlines). Without this, gemma3:4b / phi3:mini / similar sub-8B models
+ * regularly produce output the renderer rejects with "Expecting NEWLINE,
+ * got NODE_STRING".
+ */
+export function parseChartResponse(text) {
+    let body = text.trim();
+    // Strip an outer code fence if present.
+    const fenceMatch = body.match(/^```(?:mermaid)?\r?\n([\s\S]*?)\r?\n```$/);
+    if (fenceMatch) {
+        body = fenceMatch[1].trim();
+    }
+    // If the model added a preamble, find the first line that looks like a
+    // diagram-type keyword and trim everything before it. Same keyword list
+    // as chart-insert.ts's validator, kept in sync intentionally.
+    const KEYWORDS = [
+        'flowchart', 'graph',
+        'sequenceDiagram',
+        'stateDiagram-v2', 'stateDiagram',
+        'classDiagram',
+        'erDiagram',
+        'gantt', 'pie', 'journey',
+        'gitGraph',
+        'mindmap', 'timeline',
+        'quadrantChart',
+        'xychart-beta', 'sankey-beta',
+        'requirementDiagram'
+    ];
+    const lines = body.split(/\r?\n/);
+    for (let i = 0; i < lines.length; i++) {
+        const trimmed = lines[i].trim();
+        if (KEYWORDS.some((k) => new RegExp(`^${k.replace('-', '\\-')}\\b`, 'i').test(trimmed))) {
+            body = lines.slice(i).join('\n').trim();
+            return normalizeMermaidLayout(body);
+        }
+    }
+    // No keyword found anywhere — return the body as-is (still normalize, in
+    // case the keyword was on the same line as the rest) and let the
+    // validator reject it with a clear error if the normalize can't help.
+    return normalizeMermaidLayout(body);
+}
+/**
+ * Repair the "all on one line, semicolons as separators" failure mode.
+ *
+ * Mermaid's flowchart/graph/sequence/state/class/er parsers ALL require a
+ * newline after the header keyword and between every subsequent statement.
+ * Semicolons inside `[label]` brackets are fine; semicolons OUTSIDE
+ * brackets that the model is using as statement separators are not.
+ *
+ * Detection: the source is "compact" (≤2 newlines) AND contains at least
+ * one top-level semicolon. When detected, we split on top-level semicolons
+ * (skipping ones inside `[...]`, `(...)`, `{...}`, or quotes), trim each
+ * part, and emit them as separate indented lines below the header.
+ *
+ * If the source is already multi-line, this is a no-op — we don't want to
+ * accidentally rewrite hand-authored Mermaid that legitimately uses
+ * semicolons inside node labels.
+ */
+export function normalizeMermaidLayout(source) {
+    const trimmed = source.trim();
+    const lines = trimmed.split(/\r?\n/);
+    // Match the diagram header. If we can't recognize one, we have no anchor
+    // for normalization — leave the source alone and let the validator
+    // produce a clear error.
+    const headerMatch = trimmed.match(/^(flowchart|graph|sequenceDiagram|stateDiagram(?:-v2)?|classDiagram|erDiagram|gantt|pie|journey|gitGraph|mindmap|timeline|quadrantChart|xychart-beta|sankey-beta|requirementDiagram)\b\s*([A-Z]{1,4})?\s*/i);
+    if (!headerMatch)
+        return trimmed;
+    const header = headerMatch[0].trim();
+    const body = trimmed.slice(headerMatch[0].length).trim();
+    if (body.length === 0)
+        return header;
+    // Process the body line by line so a multi-line input where each line
+    // already has just one statement passes through unchanged, while a line
+    // (possibly the only line) that has MULTIPLE statements glued together
+    // gets split into separate statements.
+    //
+    // The header may have been on its own line OR fused with the first body
+    // line. Either way, `body` is now everything after the header, joined as
+    // a single string. Re-split it on existing newlines so each pre-existing
+    // line is processed for in-line statement gluing independently.
+    const bodyLines = body.split(/\r?\n/);
+    const statements = [];
+    for (const line of bodyLines) {
+        const trimmedLine = line.trim();
+        if (!trimmedLine)
+            continue;
+        // Each line: split on top-level semicolons first, then split each
+        // resulting chunk on adjacent-statement-without-separator boundaries.
+        const semiParts = splitOnTopLevelSemicolons(trimmedLine);
+        for (const part of semiParts) {
+            const trimmedPart = part.trim();
+            if (!trimmedPart)
+                continue;
+            const adjacencyParts = splitOnAdjacentStatements(trimmedPart);
+            for (const stmt of adjacencyParts) {
+                const trimmedStmt = stmt.trim();
+                if (trimmedStmt)
+                    statements.push(trimmedStmt);
+            }
+        }
+    }
+    if (statements.length === 0)
+        return header;
+    // Skip normalization entirely when nothing changed — this preserves
+    // exact whitespace for already-well-formed input. We compare against the
+    // (header on own line + each body line indented) shape we'd emit.
+    const emitted = [header, ...statements.map((s) => `  ${s}`)].join('\n');
+    return emitted;
+}
+/**
+ * Split a single body line on adjacent-statement boundaries. The failure
+ * mode this catches: a small model emits multiple statements glued together
+ * with whitespace instead of newlines.
+ *
+ * Three patterns trigger a boundary cut, all guarded to the top level
+ * (outside brackets, parens, braces, or quoted strings):
+ *
+ *   1. A closing bracket `]`, `)`, or `}` of a node label, followed by
+ *      whitespace + identifier + (another bracket OR an arrow OR a pipe).
+ *      Catches `A[X] --> B[Y] B --> C[Z]` → splits between `B[Y]` and `B`.
+ *
+ *   2. A bare identifier (no bracket label) that ends one statement,
+ *      followed by whitespace + another identifier + (bracket or arrow).
+ *      Catches `G -->|yes| F G -->|no| H[...]` → splits between `F` and
+ *      the second `G`. Without this, the bare-identifier-end case slips
+ *      through and Mermaid rejects the whole line.
+ *
+ * In all cases we advance `i` past JUST the leading whitespace (not past
+ * the identifier itself) so the next outer-loop iteration emits the
+ * identifier into the new statement.
+ */
+function splitOnAdjacentStatements(source) {
+    const ADJACENT_BOUNDARY_LOOKAHEAD = /^(\s+)[A-Za-z_][A-Za-z0-9_]*\s*(?=[\[\{\(]|--?>|---|-\.\-?>|==>|->>|--?>>|<--|\|)/;
+    const statements = [];
+    let current = '';
+    let depth = 0;
+    let inQuote = null;
+    for (let i = 0; i < source.length; i++) {
+        const ch = source[i];
+        current += ch;
+        if (inQuote) {
+            if (ch === inQuote && source[i - 1] !== '\\')
+                inQuote = null;
+            continue;
+        }
+        if (ch === '"' || ch === "'") {
+            inQuote = ch;
+            continue;
+        }
+        if (ch === '[' || ch === '(' || ch === '{') {
+            depth++;
+            continue;
+        }
+        if (ch === ']' || ch === ')' || ch === '}') {
+            depth--;
+            if (depth !== 0)
+                continue;
+            const remainder = source.slice(i + 1);
+            const m = remainder.match(ADJACENT_BOUNDARY_LOOKAHEAD);
+            if (m) {
+                statements.push(current);
+                current = '';
+                i += m[1].length;
+            }
+            continue;
+        }
+        // Bare-identifier-end boundary detection. Only fires at top-level,
+        // when the current character is the LAST character of an identifier
+        // (next character is whitespace or end-of-source) AND the identifier
+        // we just completed sits immediately after an arrow operator (so it
+        // was the destination of an edge, not the source of a new one).
+        // Without the "after-arrow" guard we'd false-cut on the SOURCE side
+        // of every edge (`A --> B` → would split between `A` and `-->`).
+        if (depth === 0 && /[A-Za-z0-9_]/.test(ch)) {
+            const nextCh = source[i + 1];
+            if (nextCh === undefined || /\s/.test(nextCh)) {
+                // Did this identifier follow an arrow? Look back through `current`
+                // for the last arrow operator before the trailing identifier.
+                // Pattern allows for an optional pipe-wrapped edge label between
+                // the arrow and the destination identifier (e.g. `--> |yes| F`).
+                const beforeIdentifier = /(-->|---|-\.->|==>|->>|<--|<-->)\s*(\|[^|]*\|)?\s*[A-Za-z_][A-Za-z0-9_]*$/;
+                if (beforeIdentifier.test(current)) {
+                    const remainder = source.slice(i + 1);
+                    const m = remainder.match(ADJACENT_BOUNDARY_LOOKAHEAD);
+                    if (m) {
+                        statements.push(current);
+                        current = '';
+                        i += m[1].length;
+                    }
+                }
+            }
+        }
+    }
+    if (current.length > 0)
+        statements.push(current);
+    return statements;
+}
+function countTopLevelSemicolons(source) {
+    let count = 0;
+    let depth = 0;
+    let inQuote = null;
+    for (let i = 0; i < source.length; i++) {
+        const ch = source[i];
+        if (inQuote) {
+            if (ch === inQuote && source[i - 1] !== '\\')
+                inQuote = null;
+            continue;
+        }
+        if (ch === '"' || ch === "'") {
+            inQuote = ch;
+            continue;
+        }
+        if (ch === '[' || ch === '(' || ch === '{')
+            depth++;
+        else if (ch === ']' || ch === ')' || ch === '}')
+            depth--;
+        else if (ch === ';' && depth === 0)
+            count++;
+    }
+    return count;
+}
+function splitOnTopLevelSemicolons(source) {
+    const parts = [];
+    let buffer = '';
+    let depth = 0;
+    let inQuote = null;
+    for (let i = 0; i < source.length; i++) {
+        const ch = source[i];
+        if (inQuote) {
+            buffer += ch;
+            if (ch === inQuote && source[i - 1] !== '\\')
+                inQuote = null;
+            continue;
+        }
+        if (ch === '"' || ch === "'") {
+            inQuote = ch;
+            buffer += ch;
+            continue;
+        }
+        if (ch === '[' || ch === '(' || ch === '{') {
+            depth++;
+            buffer += ch;
+            continue;
+        }
+        if (ch === ']' || ch === ')' || ch === '}') {
+            depth--;
+            buffer += ch;
+            continue;
+        }
+        if (ch === ';' && depth === 0) {
+            parts.push(buffer);
+            buffer = '';
+            continue;
+        }
+        buffer += ch;
+    }
+    if (buffer.length > 0)
+        parts.push(buffer);
+    return parts;
+}

package/dist/context-cache.js

@@ -0,0 +1,98 @@
+/**
+ * LRU + TTL cache for `wiki_context` results.
+ *
+ * Process-local, in-memory, capped at 256 entries with a 30-minute TTL. Ported from
+ * dendrite-mcp's packet_cache.rs. Invalidated on any `wiki_write`, `memory_remember`,
+ * `memory_forget`, `memory_restore`, or `memory_promote` call so writes don't serve
+ * stale briefings.
+ *
+ * Explicit design trade-off: cache hits do NOT re-bump `recallCount` or `lastRecalledAt`
+ * for the surfaced memories. The 30-minute TTL keeps the staleness window tight, and the
+ * latency win on repeated `wiki_context` calls within the same task is the goal — perfect
+ * recall-count fidelity is not. If real-world usage shows recall counts meaningfully
+ * undercounting, revisit.
+ */
+import { onMemoryMutation } from '@rarusoft/dendrite-memory';
+const MAX_ENTRIES = 256;
+const TTL_MS = 30 * 60 * 1000;
+const entries = new Map();
+export function getCachedWikiContext(query, options) {
+    const key = buildCacheKey(query, options);
+    const entry = entries.get(key);
+    if (!entry) {
+        return undefined;
+    }
+    const now = Date.now();
+    if (now - entry.insertedAt > TTL_MS) {
+        entries.delete(key);
+        return undefined;
+    }
+    entry.lastHitAt = now;
+    entry.hitCount += 1;
+    return entry.result;
+}
+export function setCachedWikiContext(query, options, result) {
+    const key = buildCacheKey(query, options);
+    if (entries.size >= MAX_ENTRIES && !entries.has(key)) {
+        evictOldest();
+    }
+    const now = Date.now();
+    entries.set(key, {
+        key,
+        result,
+        insertedAt: now,
+        lastHitAt: now,
+        hitCount: 0
+    });
+}
+export function invalidateWikiContextCache() {
+    entries.clear();
+}
+// Phase 4 slice B wave 2: cache invalidation is now wiki-side and listens to brain
+// mutation events rather than being called from inside memory-store.ts. The
+// registration runs once at module load; the listener stays alive for the process
+// lifetime (no unsubscribe needed in normal operation).
+onMemoryMutation(invalidateWikiContextCache);
+export function getWikiContextCacheStats() {
+    let totalHits = 0;
+    for (const entry of entries.values()) {
+        totalHits += entry.hitCount;
+    }
+    return {
+        size: entries.size,
+        maxEntries: MAX_ENTRIES,
+        ttlMs: TTL_MS,
+        totalHits
+    };
+}
+function buildCacheKey(query, options) {
+    // Stable JSON ordering: explicitly serialize keys so two calls with the same args but
+    // different option-property declaration order map to the same cache entry.
+    return JSON.stringify({
+        q: query,
+        mp: options.maxPages ?? null,
+        il: options.includeLint ?? null,
+        ml: options.maxLogEntries ?? null,
+        ms: options.maxSkills ?? null,
+        rf: normalizeOptionalArray(options.relatedFiles),
+        l: normalizeOptionalArray(options.languages),
+        fw: normalizeOptionalArray(options.frameworks)
+    });
+}
+function normalizeOptionalArray(value) {
+    if (!Array.isArray(value) || value.length === 0) {
+        return null;
+    }
+    return [...value].map((v) => v.toLowerCase()).sort();
+}
+function evictOldest() {
+    let oldestEntry;
+    for (const entry of entries.values()) {
+        if (!oldestEntry || entry.lastHitAt < oldestEntry.lastHitAt) {
+            oldestEntry = entry;
+        }
+    }
+    if (oldestEntry) {
+        entries.delete(oldestEntry.key);
+    }
+}