@doquflow/server 0.2.0 → 0.3.0

package/dist/tools/preview-generation.js

@@ -0,0 +1,212 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.previewGeneration = previewGeneration;
+const node_path_1 = __importDefault(require("node:path"));
+/**
+ * preview_generation
+ *
+ * Shows what a tool will generate before it actually runs.
+ * Removes black-box feeling by providing transparency.
+ *
+ * Input:
+ * - tool_name: string (the tool you want to run)
+ * - project_path: string
+ * - params: Record<string, any> (the parameters you'd pass to the tool)
+ *
+ * Output:
+ * - Predicted actions and outputs
+ * - Files that will be affected
+ * - Impact level (low/medium/high)
+ * - Recommendation on whether to proceed
+ */
+async function previewGeneration(input) {
+    const projectPath = node_path_1.default.resolve(input.project_path);
+    const toolName = input.tool_name;
+    const params = input.params;
+    // Define preview for each tool
+    const previews = {
+        ingest_source: (projectPath, params) => ({
+            tool_name: "ingest_source",
+            tool_description: "Process a new source and integrate it into the wiki",
+            input_provided: params,
+            predicted_actions: [
+                "✓ Read the source file(s)",
+                "✓ Extract entities and concepts",
+                "✓ Generate or update wiki pages",
+                "✓ Create cross-references",
+                "✓ Update index.md with new entities",
+                "✓ Append entry to log.md",
+            ],
+            predicted_outputs: [
+                {
+                    type: "Wiki Pages",
+                    description: "5-20 new or updated wiki pages depending on source size",
+                    example: "entities/ServiceName.md, concepts/Pattern.md, syntheses/Integration.md",
+                },
+                {
+                    type: "Index Update",
+                    description: "Updated index.md with new pages and metadata",
+                    example: "index.md entry with source, date, page count",
+                },
+                {
+                    type: "Log Entry",
+                    description: "New line in log.md documenting the ingest",
+                    example: "[2026-04-17 14:23] ingest | source_name.md → 12 pages created, 5 updated",
+                },
+            ],
+            data_modified: true,
+            files_affected: [
+                ".docuflow/wiki/entities/*.md",
+                ".docuflow/wiki/concepts/*.md",
+                ".docuflow/wiki/syntheses/*.md",
+                ".docuflow/index.md",
+                ".docuflow/log.md",
+            ],
+            estimated_impact: "high",
+            proceed_recommendation: "✓ Safe to proceed. Source will be integrated and wiki will grow. This is expected behavior.",
+        }),
+        query_wiki: (projectPath, params) => ({
+            tool_name: "query_wiki",
+            tool_description: "Search and synthesize answers from the wiki",
+            input_provided: params,
+            predicted_actions: [
+                "✓ Search index.md for relevant pages",
+                "✓ Read matching wiki pages",
+                "✓ Synthesize answer with citations",
+                "✓ Return answer with source pages",
+            ],
+            predicted_outputs: [
+                {
+                    type: "Answer",
+                    description: "Synthesized answer to your question",
+                    example: 'The system uses MCP protocol to communicate with tools...',
+                },
+                {
+                    type: "Source Pages",
+                    description: "Wiki pages used to create the answer",
+                    example: "concepts/MCP_Protocol.md, entities/Server.md",
+                },
+                {
+                    type: "Confidence",
+                    description: "How well the question was answered (0-100)",
+                    example: "85 (good coverage, some gaps possible)",
+                },
+            ],
+            data_modified: false,
+            files_affected: [],
+            estimated_impact: "low",
+            proceed_recommendation: "✓ Safe to proceed. This is a read-only operation. No wiki data will be changed.",
+        }),
+        lint_wiki: (projectPath, params) => ({
+            tool_name: "lint_wiki",
+            tool_description: "Health check the wiki for issues",
+            input_provided: params,
+            predicted_actions: [
+                "✓ Scan for orphan pages (no incoming links)",
+                "✓ Find stale pages (30+ days old)",
+                "✓ Check for broken cross-references",
+                "✓ Detect contradictions in content",
+                "✓ Look for metadata gaps",
+                "✓ Calculate overall health score",
+            ],
+            predicted_outputs: [
+                {
+                    type: "Issues",
+                    description: "Potential problems found in the wiki",
+                    example: "5 orphan pages, 2 stale (>30 days), 3 broken references",
+                },
+                {
+                    type: "Health Score",
+                    description: "Overall wiki health (0-100)",
+                    example: "78/100 (Good, some maintenance recommended)",
+                },
+                {
+                    type: "Recommendations",
+                    description: "Actionable suggestions to improve wiki",
+                    example: "Delete orphans, update stale pages, add missing cross-refs",
+                },
+            ],
+            data_modified: false,
+            files_affected: [],
+            estimated_impact: "low",
+            proceed_recommendation: "✓ Safe to proceed. This is a read-only diagnostic. It will report issues but not fix them.",
+        }),
+        save_answer_as_page: (projectPath, params) => ({
+            tool_name: "save_answer_as_page",
+            tool_description: "Save an answer as a new wiki page (enables knowledge compounding)",
+            input_provided: params,
+            predicted_actions: [
+                "✓ Extract the answer from conversation",
+                "✓ Create markdown file with frontmatter metadata",
+                "✓ Place in appropriate category (synthesis or concept)",
+                "✓ Update index.md with new page",
+                "✓ Add log entry",
+            ],
+            predicted_outputs: [
+                {
+                    type: "New Wiki Page",
+                    description: "New markdown file in wiki/syntheses/ or wiki/concepts/",
+                    example: ".docuflow/wiki/syntheses/query_result_20260417.md",
+                },
+                {
+                    type: "Metadata",
+                    description: "YAML frontmatter with creation date, tags, sources",
+                    example: "created_at: 2026-04-17, sources: [5 pages], tags: [architecture]",
+                },
+            ],
+            data_modified: true,
+            files_affected: [
+                ".docuflow/wiki/syntheses/*.md or concepts/*.md",
+                ".docuflow/index.md",
+                ".docuflow/log.md",
+            ],
+            estimated_impact: "medium",
+            proceed_recommendation: "✓ This compounds knowledge in your wiki! Proceed to file interesting discoveries.",
+        }),
+        lint_wiki_with_check: (projectPath, params) => ({
+            tool_name: "lint_wiki",
+            tool_description: "Run specific lint check on the wiki",
+            input_provided: params,
+            predicted_actions: [
+                `✓ Run ${params.check_type || "all"} lint checks`,
+                "✓ Analyze wiki for specific issues",
+                "✓ Generate targeted recommendations",
+            ],
+            predicted_outputs: [
+                {
+                    type: "Check Results",
+                    description: `Results for ${params.check_type || "all checks"}`,
+                    example: "5 issues found of this type",
+                },
+                {
+                    type: "Recommendations",
+                    description: "How to fix the issues",
+                    example: "Delete orphan pages, add missing references",
+                },
+            ],
+            data_modified: false,
+            files_affected: [],
+            estimated_impact: "low",
+            proceed_recommendation: "✓ Safe to proceed. This is diagnostic and won't modify wiki data.",
+        }),
+    };
+    // Get preview based on tool name
+    const previewFn = previews[toolName];
+    if (!previewFn) {
+        return {
+            tool_name: toolName,
+            tool_description: "Unknown tool",
+            input_provided: params,
+            predicted_actions: ["❌ Tool not found"],
+            predicted_outputs: [],
+            data_modified: false,
+            files_affected: [],
+            estimated_impact: "low",
+            proceed_recommendation: "❌ Unknown tool. Check tool name and try again.",
+        };
+    }
+    return previewFn(projectPath, params);
+}

package/dist/tools/query-wiki.js

@@ -0,0 +1,67 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.queryWiki = queryWiki;
+const node_path_1 = __importDefault(require("node:path"));
+const wiki_search_1 = require("./wiki-search");
+const answer_synthesis_1 = require("./answer-synthesis");
+async function queryWiki(input) {
+    try {
+        const projectPath = node_path_1.default.resolve(input.project_path);
+        const maxSources = input.max_sources ?? 5;
+        // Step 1: Search the wiki for relevant pages
+        const searchResult = await (0, wiki_search_1.wikiSearch)({
+            project_path: projectPath,
+            query: input.question,
+            limit: Math.max(10, maxSources * 2), // Get extra to filter
+        });
+        if (searchResult.error || !searchResult.results.length) {
+            return {
+                question: input.question,
+                answer: `No relevant wiki pages found for: ${input.question}`,
+                source_pages: [],
+                search_results: 0,
+                confidence: 0,
+                error: searchResult.error,
+            };
+        }
+        // Step 2: Select top N results for synthesis
+        const topResults = searchResult.results.slice(0, maxSources);
+        const sourcePageIds = topResults.map((r) => r.page_id);
+        // Step 3: Synthesize answer from selected pages
+        const synthesisResult = await (0, answer_synthesis_1.synthesizeAnswer)({
+            project_path: projectPath,
+            query: input.question,
+            source_page_ids: sourcePageIds,
+        });
+        if (synthesisResult.error) {
+            return {
+                question: input.question,
+                answer: `Error synthesizing answer: ${synthesisResult.error}`,
+                source_pages: synthesisResult.source_pages,
+                search_results: searchResult.total_results,
+                confidence: 0,
+                error: synthesisResult.error,
+            };
+        }
+        return {
+            question: input.question,
+            answer: synthesisResult.answer,
+            source_pages: synthesisResult.source_pages,
+            search_results: searchResult.total_results,
+            confidence: synthesisResult.confidence,
+        };
+    }
+    catch (e) {
+        return {
+            question: input.question,
+            answer: `Query failed: ${e?.message ?? String(e)}`,
+            source_pages: [],
+            search_results: 0,
+            confidence: 0,
+            error: e?.message ?? String(e),
+        };
+    }
+}

package/dist/tools/save-answer-as-page.js

@@ -0,0 +1,96 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.saveAnswerAsPage = saveAnswerAsPage;
+const node_path_1 = __importDefault(require("node:path"));
+const promises_1 = __importDefault(require("node:fs/promises"));
+const filesystem_1 = require("../filesystem");
+async function saveAnswerAsPage(input) {
+    try {
+        const projectPath = node_path_1.default.resolve(input.project_path);
+        const docuDir = node_path_1.default.join(projectPath, ".docuflow");
+        const wikiDir = node_path_1.default.join(docuDir, "wiki");
+        // Use provided category or default to synthesis
+        const category = input.category ?? "synthesis";
+        const categoryDir = node_path_1.default.join(wikiDir, category + "s");
+        await (0, filesystem_1.ensureDir)(categoryDir);
+        // Generate page ID from title
+        const pageId = `query_${input.page_title
+            .toLowerCase()
+            .replace(/[^a-z0-9]/g, "_")
+            .replace(/_+/g, "_")
+            .substring(0, 50)}`;
+        // Generate frontmatter
+        const now = new Date().toISOString();
+        const sources = input.source_page_ids ?? [];
+        const frontmatterYaml = `---
+created_at: ${now}
+updated_at: ${now}
+sources: ${JSON.stringify(sources)}
+tags: ["query_result","synthesis"]
+inbound_links: ${JSON.stringify([])}
+outbound_links: ${JSON.stringify(sources)}
+---
+`;
+        // Build page content
+        const pageContent = `${frontmatterYaml}
+# ${input.page_title}
+
+**Generated from query**: ${input.question}
+
+**Synthesis timestamp**: ${now}
+
+## Answer
+
+${input.answer}
+
+## Related Pages
+
+${sources.length > 0
+            ? sources.map((s) => `- [\`${s}\`](../CATEGORY/${s}.md)`).join("\n")
+            : "No source pages linked."}
+
+---
+
+*This page was generated by synthesizing answers from multiple wiki pages.*
+*To refine further, add more source documents and re-ingest.*
+`;
+        // Write the page file
+        const pageFile = node_path_1.default.join(categoryDir, `${pageId}.md`);
+        const bytes = await (0, filesystem_1.writeFileAtomic)(pageFile, pageContent);
+        // Also update log.md to record this
+        const logFile = node_path_1.default.join(docuDir, "log.md");
+        try {
+            let logContent = "";
+            try {
+                const logRead = await promises_1.default.readFile(logFile, "utf-8");
+                logContent = logRead;
+            }
+            catch (e) {
+                logContent = "# Operation Log\n\n";
+            }
+            const timestamp = now.split("T")[0]; // YYYY-MM-DD
+            const logEntry = `## [${timestamp}] query-result | Saved answer as ${pageId}\n\n`;
+            logContent += logEntry;
+            await (0, filesystem_1.writeFileAtomic)(logFile, logContent);
+        }
+        catch (e) {
+            // Log update failure is not critical
+        }
+        return {
+            saved_page_id: pageId,
+            saved_path: node_path_1.default.relative(docuDir, pageFile),
+            category,
+        };
+    }
+    catch (e) {
+        return {
+            saved_page_id: "",
+            saved_path: "",
+            category: input.category ?? "synthesis",
+            error: e?.message ?? String(e),
+        };
+    }
+}

package/dist/tools/update-index.js

@@ -0,0 +1,151 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.updateIndex = updateIndex;
+const node_path_1 = __importDefault(require("node:path"));
+const promises_1 = __importDefault(require("node:fs/promises"));
+const filesystem_1 = require("../filesystem");
+/**
+ * Parse frontmatter from a markdown file.
+ * Expects YAML format between --- markers.
+ */
+function parseFrontmatter(content) {
+    const match = content.match(/^---\n([\s\S]*?)\n---/);
+    if (!match)
+        return {};
+    const yaml = match[1];
+    const result = {};
+    for (const line of yaml.split("\n")) {
+        if (!line.trim())
+            continue;
+        const [key, ...valueParts] = line.split(":");
+        const value = valueParts.join(":").trim();
+        try {
+            // Try to parse as JSON (arrays, objects)
+            if (value.startsWith("[") || value.startsWith("{")) {
+                result[key.trim()] = JSON.parse(value);
+            }
+            else {
+                result[key.trim()] = value;
+            }
+        }
+        catch {
+            result[key.trim()] = value;
+        }
+    }
+    return result;
+}
+/**
+ * Extract title from markdown content.
+ * Looks for first H1 header.
+ */
+function extractTitle(content) {
+    const match = content.match(/^#\s+(.+?)$/m);
+    return match ? match[1].trim() : "Untitled";
+}
+/**
+ * Scan all wiki pages and regenerate index.md
+ */
+async function updateIndex(input) {
+    try {
+        const projectPath = node_path_1.default.resolve(input.project_path);
+        const docuDir = node_path_1.default.join(projectPath, ".docuflow");
+        const wikiDir = node_path_1.default.join(docuDir, "wiki");
+        const indexFile = node_path_1.default.join(docuDir, "index.md");
+        const logFile = node_path_1.default.join(docuDir, "log.md");
+        // Scan all wiki pages
+        const entries = [];
+        const categories = ["entities", "concepts", "timelines", "syntheses"];
+        for (const category of categories) {
+            const categoryDir = node_path_1.default.join(wikiDir, category);
+            try {
+                const files = await promises_1.default.readdir(categoryDir);
+                for (const file of files) {
+                    if (!file.endsWith(".md"))
+                        continue;
+                    const filePath = node_path_1.default.join(categoryDir, file);
+                    const read = await (0, filesystem_1.safeReadFile)(filePath);
+                    if (read.error || read.binary || !read.content)
+                        continue;
+                    const fm = parseFrontmatter(read.content);
+                    const title = extractTitle(read.content);
+                    const pageId = file.replace(".md", "");
+                    entries.push({
+                        id: pageId,
+                        title,
+                        category: category.replace("s", ""), // entities → entity
+                        path: node_path_1.default.relative(docuDir, filePath),
+                        created_at: fm.created_at ?? new Date().toISOString(),
+                    });
+                }
+            }
+            catch (e) {
+                // Category dir may not exist yet
+            }
+        }
+        // Generate index.md content
+        const now = new Date().toISOString();
+        let indexContent = `# Wiki Index
+
+Generated: ${now}
+
+## Overview
+
+Total pages: ${entries.length}
+
+## By Category
+
+`;
+        // Group by category
+        const byCategory = {};
+        for (const entry of entries) {
+            if (!byCategory[entry.category])
+                byCategory[entry.category] = [];
+            byCategory[entry.category].push(entry);
+        }
+        // Add each category section
+        for (const category of ["entity", "concept", "timeline", "synthesis"]) {
+            const categoryEntries = byCategory[category] || [];
+            if (categoryEntries.length === 0)
+                continue;
+            indexContent += `### ${category.charAt(0).toUpperCase() + category.slice(1)} Pages (${categoryEntries.length})\n\n`;
+            for (const entry of categoryEntries.sort((a, b) => a.title.localeCompare(b.title))) {
+                indexContent += `- [\`${entry.id}\`](./${entry.path}) — **${entry.title}**\n`;
+            }
+            indexContent += "\n";
+        }
+        // Write index.md
+        await (0, filesystem_1.ensureDir)(docuDir);
+        await (0, filesystem_1.writeFileAtomic)(indexFile, indexContent);
+        // Append to log.md
+        let logUpdated = false;
+        try {
+            const logRead = await (0, filesystem_1.safeReadFile)(logFile);
+            let logContent = logRead.content ?? "# Operation Log\n\n";
+            // Add entry
+            const timestamp = now.split("T")[0]; // YYYY-MM-DD
+            const logEntry = `## [${timestamp}] index-update | ${entries.length} pages indexed\n\n`;
+            logContent += logEntry;
+            await (0, filesystem_1.writeFileAtomic)(logFile, logContent);
+            logUpdated = true;
+        }
+        catch (e) {
+            // Log may not exist, that's ok
+        }
+        return {
+            entries_indexed: entries.length,
+            index_file: indexFile,
+            log_appended: logUpdated,
+        };
+    }
+    catch (e) {
+        return {
+            entries_indexed: 0,
+            index_file: "",
+            log_appended: false,
+            error: e?.message ?? String(e),
+        };
+    }
+}

package/dist/tools/wiki-search.js

@@ -0,0 +1,151 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.wikiSearch = wikiSearch;
+const node_path_1 = __importDefault(require("node:path"));
+const promises_1 = __importDefault(require("node:fs/promises"));
+const filesystem_1 = require("../filesystem");
+/**
+ * Simple BM25-inspired scoring with term frequency and document frequency.
+ * Weights entity pages more heavily than concepts, titles match higher.
+ */
+function scoreMatch(query, content, title, category, totalPages) {
+    const queryTerms = query.toLowerCase().split(/\s+/).filter((t) => t.length > 2);
+    let score = 0;
+    const matched_terms = new Set();
+    for (const term of queryTerms) {
+        // Title match (highest weight)
+        if (title.toLowerCase().includes(term)) {
+            score += 50;
+            matched_terms.add(term);
+        }
+        // Content match with term frequency (TF)
+        const contentLower = content.toLowerCase();
+        const termRegex = new RegExp(`\\b${term}\\b`, "gi");
+        const matches = contentLower.match(termRegex);
+        if (matches) {
+            const tf = matches.length;
+            // Inverse document frequency approximation
+            const idf = Math.log(totalPages / Math.max(1, matches.length));
+            score += tf * idf * 2;
+            matched_terms.add(term);
+        }
+    }
+    // Category boost: entities score higher than concepts
+    if (category === "entity") {
+        score *= 1.3;
+    }
+    else if (category === "synthesis") {
+        score *= 1.1;
+    }
+    return { score, matched_terms: Array.from(matched_terms) };
+}
+/**
+ * Extract a preview snippet from content around matched terms
+ */
+function extractPreview(content, matchedTerms, maxLength = 150) {
+    if (!matchedTerms.length) {
+        // Return first non-empty paragraph
+        const lines = content.split("\n").filter((l) => l.trim() && !l.startsWith("#") && !l.startsWith("---"));
+        return lines.slice(0, 2).join(" ").substring(0, maxLength);
+    }
+    // Find first occurrence of any matched term
+    const contentLower = content.toLowerCase();
+    const term = matchedTerms[0];
+    const index = contentLower.indexOf(term);
+    if (index === -1) {
+        const lines = content.split("\n").filter((l) => l.trim() && !l.startsWith("#"));
+        return lines.slice(0, 2).join(" ").substring(0, maxLength);
+    }
+    const start = Math.max(0, index - 60);
+    const end = Math.min(content.length, index + 150);
+    let preview = content.substring(start, end);
+    // Trim to word boundary
+    const lastSpace = preview.lastIndexOf(" ");
+    if (lastSpace > 0) {
+        preview = preview.substring(0, lastSpace) + "...";
+    }
+    return preview;
+}
+async function wikiSearch(input) {
+    try {
+        const projectPath = node_path_1.default.resolve(input.project_path);
+        const docuDir = node_path_1.default.join(projectPath, ".docuflow");
+        const wikiDir = node_path_1.default.join(docuDir, "wiki");
+        const limit = input.limit ?? 10;
+        const allResults = [];
+        // Build list of categories to search
+        let categoriesToScan = ["entities", "concepts", "timelines", "syntheses"];
+        if (input.category) {
+            categoriesToScan = [`${input.category}s`];
+        }
+        // First pass: count total pages (for IDF calculation)
+        let totalPages = 0;
+        for (const categoryDir of categoriesToScan) {
+            const fullCategoryPath = node_path_1.default.join(wikiDir, categoryDir);
+            try {
+                const files = await promises_1.default.readdir(fullCategoryPath);
+                totalPages += files.filter((f) => f.endsWith(".md")).length;
+            }
+            catch (e) {
+                // Category may not exist
+            }
+        }
+        // Second pass: search all pages
+        for (const categoryDir of categoriesToScan) {
+            const fullCategoryPath = node_path_1.default.join(wikiDir, categoryDir);
+            const category = categoryDir.replace("s", ""); // entities → entity
+            try {
+                const files = await promises_1.default.readdir(fullCategoryPath);
+                for (const file of files) {
+                    if (!file.endsWith(".md"))
+                        continue;
+                    const filePath = node_path_1.default.join(fullCategoryPath, file);
+                    const read = await (0, filesystem_1.safeReadFile)(filePath);
+                    if (read.error || read.binary || !read.content)
+                        continue;
+                    // Extract title from content (first H1)
+                    const titleMatch = read.content.match(/^#\s+(.+?)$/m);
+                    const title = titleMatch ? titleMatch[1].trim() : file.replace(".md", "");
+                    const pageId = file.replace(".md", "");
+                    // Score the match
+                    const { score, matched_terms } = scoreMatch(input.query, read.content, title, category, totalPages);
+                    // Only include if there's at least one match
+                    if (score > 0 && matched_terms.length > 0) {
+                        const preview = extractPreview(read.content, matched_terms);
+                        allResults.push({
+                            page_id: pageId,
+                            title,
+                            category,
+                            path: node_path_1.default.relative(docuDir, filePath),
+                            relevance_score: Math.round(score * 10) / 10, // Round to 1 decimal
+                            preview,
+                            matched_terms,
+                        });
+                    }
+                }
+            }
+            catch (e) {
+                // Category directory may not exist
+            }
+        }
+        // Sort by relevance score (descending) and return top N
+        allResults.sort((a, b) => b.relevance_score - a.relevance_score);
+        const results = allResults.slice(0, limit);
+        return {
+            query: input.query,
+            results,
+            total_results: allResults.length,
+        };
+    }
+    catch (e) {
+        return {
+            query: input.query,
+            results: [],
+            total_results: 0,
+            error: e?.message ?? String(e),
+        };
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@doquflow/server",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Docuflow MCP server — lets AI agents read codebases and persist living specs",
   "author": "Docuflow <hello@doquflows.dev>",
   "license": "MIT",