@doquflow/server 0.2.0 → 0.4.0

package/dist/tools/preview-generation.js

@@ -0,0 +1,228 @@
+"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"));
+const promises_1 = __importDefault(require("node:fs/promises"));
+async function countWikiPages(wikiDir) {
+    let total = 0;
+    for (const cat of ["entities", "concepts", "timelines", "syntheses"]) {
+        try {
+            const files = await promises_1.default.readdir(node_path_1.default.join(wikiDir, cat));
+            total += files.filter((f) => f.endsWith(".md")).length;
+        }
+        catch {
+            // directory may not exist
+        }
+    }
+    return total;
+}
+async function getSourceFileSize(sourcesDir, filename) {
+    try {
+        const stat = await promises_1.default.stat(node_path_1.default.join(sourcesDir, filename));
+        return stat.size;
+    }
+    catch {
+        return 0;
+    }
+}
+function predictPageCount(fileSizeBytes) {
+    // Rough heuristic: ~1 wiki page per 800 bytes of source
+    const low = Math.max(1, Math.floor(fileSizeBytes / 1200));
+    const high = Math.max(2, Math.ceil(fileSizeBytes / 600));
+    return `${low}–${high}`;
+}
+/**
+ * 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 docuDir = node_path_1.default.join(projectPath, ".docuflow");
+    const wikiDir = node_path_1.default.join(docuDir, "wiki");
+    const sourcesDir = node_path_1.default.join(docuDir, "sources");
+    const toolName = input.tool_name;
+    const params = input.params;
+    // Read real wiki state upfront
+    const existingPageCount = await countWikiPages(wikiDir);
+    if (toolName === "ingest_source") {
+        const filename = params.source_filename ?? "";
+        const fileSize = await getSourceFileSize(sourcesDir, filename);
+        const predictedNew = predictPageCount(fileSize);
+        const sizeLabel = fileSize > 0 ? `${Math.round(fileSize / 1024)}KB` : "unknown size";
+        return {
+            tool_name: "ingest_source",
+            tool_description: "Process a new source and integrate it into the wiki",
+            input_provided: params,
+            predicted_actions: [
+                `✓ Read ${filename} (${sizeLabel})`,
+                "✓ Extract entities and concepts from markdown",
+                "✓ Generate wiki pages (one per entity/concept found)",
+                "✓ Create cross-references between pages",
+                "✓ Update index.md with new entries",
+                "✓ Append entry to log.md",
+            ],
+            predicted_outputs: [
+                {
+                    type: "Wiki Pages",
+                    description: `Estimated ${predictedNew} new pages (wiki currently has ${existingPageCount})`,
+                    example: "entities/ServiceName.md, concepts/Pattern.md, syntheses/source_name.md",
+                },
+                {
+                    type: "Index Update",
+                    description: "index.md gets new page entries with metadata",
+                    example: "index.md entry with source, date, page count",
+                },
+                {
+                    type: "Log Entry",
+                    description: "log.md records this ingest",
+                    example: `[${new Date().toISOString().slice(0, 10)}] ingest | ${filename} → N pages created`,
+                },
+            ],
+            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.",
+        };
+    }
+    if (toolName === "query_wiki") {
+        return {
+            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 from up to ${existingPageCount} wiki pages`,
+                    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: existingPageCount > 10 ? "85 (good coverage)" : "50 (sparse wiki — add more sources)",
+                },
+            ],
+            data_modified: false,
+            files_affected: [],
+            estimated_impact: "low",
+            proceed_recommendation: existingPageCount === 0
+                ? "⚠ Wiki is empty — ingest sources first for useful answers."
+                : "✓ Safe to proceed. This is a read-only operation. No wiki data will be changed.",
+        };
+    }
+    if (toolName === "lint_wiki") {
+        return {
+            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: `Scanning ${existingPageCount} wiki pages for problems`,
+                    example: "N orphan pages, N stale (>30 days), N broken references",
+                },
+                {
+                    type: "Health Score",
+                    description: "Overall wiki health (0-100)",
+                    example: existingPageCount > 0 ? "Score will vary — run to find out" : "N/A (no pages yet)",
+                },
+                {
+                    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: existingPageCount === 0
+                ? "⚠ Wiki is empty — nothing to lint yet. Ingest sources first."
+                : "✓ Safe to proceed. This is a read-only diagnostic. It will report issues but not fix them.",
+        };
+    }
+    if (toolName === "save_answer_as_page") {
+        return {
+            tool_name: "save_answer_as_page",
+            tool_description: "Save an answer as a new wiki page (enables knowledge compounding)",
+            input_provided: params,
+            predicted_actions: [
+                "✓ Format the answer as markdown with frontmatter",
+                "✓ 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 — wiki will have ${existingPageCount + 1} pages`,
+                    example: ".docuflow/wiki/syntheses/query_result_<date>.md",
+                },
+                {
+                    type: "Metadata",
+                    description: "YAML frontmatter with creation date, tags, sources",
+                    example: `created_at: ${new Date().toISOString().slice(0, 10)}, tags: [synthesis]`,
+                },
+            ],
+            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.",
+        };
+    }
+    // Unknown tool fallback
+    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.",
+    };
+}

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/read-specs.js

@@ -7,6 +7,7 @@ exports.readSpecs = readSpecs;
 const node_path_1 = __importDefault(require("node:path"));
 const promises_1 = __importDefault(require("node:fs/promises"));
 const filesystem_1 = require("../filesystem");
+const STALE_DAYS = 30;
 async function readSpecs(input) {
     const projectPath = node_path_1.default.resolve(input.project_path);
     const docuDir = node_path_1.default.join(projectPath, ".docuflow");
@@ -20,12 +21,15 @@ async function readSpecs(input) {
         const needle = input.module_name.replace(/\.md$/i, "").toLowerCase();
         entries = entries.filter((s) => s.filename.replace(/\.md$/i, "").toLowerCase() === needle);
     }
+    const now = Date.now();
     const specs = [];
     for (const entry of entries) {
         const filePath = node_path_1.default.join(docuDir, "specs", entry.filename);
         try {
             const content = await promises_1.default.readFile(filePath, "utf8");
-            specs.push({ filename: entry.filename, written_at: entry.written_at, content });
+            const writtenMs = entry.written_at ? new Date(entry.written_at).getTime() : NaN;
+            const stale = !isNaN(writtenMs) && (now - writtenMs) > STALE_DAYS * 86_400_000;
+            specs.push({ filename: entry.filename, written_at: entry.written_at, stale, content });
         }
         catch {
             // spec entry exists in index but file missing — skip silently

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

@@ -0,0 +1,102 @@
+"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)}
+---
+`;
+        const CATEGORY_DIR = {
+            synthesis: "syntheses",
+            entity: "entities",
+            concept: "concepts",
+            timeline: "timelines",
+        };
+        // 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_DIR[category] ?? category + "s"}/${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,157 @@
+"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"];
+        const PLURAL_TO_SINGULAR = {
+            entities: "entity",
+            concepts: "concept",
+            timelines: "timeline",
+            syntheses: "synthesis",
+        };
+        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: PLURAL_TO_SINGULAR[category] ?? category.replace(/s$/, ""),
+                        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),
+        };
+    }
+}