@doquflow/server 0.1.1 → 0.3.0

package/dist/extractor.js

@@ -37,6 +37,12 @@ const RE_MIN_API = /\bapp\.Map(?:Get|Post|Put|Delete|Patch)\s*\(\s*["']([^"']+)[
 const RE_EXPRESS = /\b(?:router|app)\.(?:get|post|put|delete|patch|use)\s*\(\s*['"]([^'"]+)['"]/g;
 const RE_NEST = /@(?:Get|Post|Put|Delete|Patch)\s*\(\s*['"]([^'"]+)['"]/g;
 const RE_NG_PATH = /\bpath\s*:\s*['"]([^'"]+)['"]/g;
+// Flask: @app.route('/path') @bp.route('/path')
+const RE_FLASK = /@\w+\.route\s*\(\s*['"]([^'"]+)['"]/g;
+// FastAPI / Flask-style: @app.get('/x') @router.post('/x')
+const RE_FASTAPI = /@(?:app|router|bp)\s*\.\s*(?:get|post|put|delete|patch)\s*\(\s*['"]([^'"]+)['"]/g;
+// Django: path('url/', view) url('pattern/', view)
+const RE_DJANGO = /\bpath\s*\(\s*['"]([^'"]+)['"]/g;
 const RE_CFG_CONNSTR = /\bConnectionStrings:([\w.]+)/g;
 const RE_PROCESS_ENV = /\bprocess\.env\.([A-Z_][A-Z0-9_]*)/g;
 const RE_DOTNET_ENV = /\bEnvironment\.GetEnvironmentVariable\(\s*["']([^"']+)["']/g;
@@ -97,6 +103,9 @@ function extract(content) {
         ...collect(new RegExp(RE_EXPRESS.source, "g"), content),
         ...collect(new RegExp(RE_NEST.source, "g"), content),
         ...collect(new RegExp(RE_NG_PATH.source, "g"), content),
+        ...collect(new RegExp(RE_FLASK.source, "g"), content),
+        ...collect(new RegExp(RE_FASTAPI.source, "g"), content),
+        ...collect(new RegExp(RE_DJANGO.source, "g"), content),
     ]);
     const config_refs = [];
     config_refs.push(...collect(new RegExp(RE_CFG_CONNSTR.source, "g"), content).map((s) => `ConnectionStrings:${s}`));

package/dist/index.js

@@ -8,6 +8,16 @@ const read_module_1 = require("./tools/read-module");
 const list_modules_1 = require("./tools/list-modules");
 const write_spec_1 = require("./tools/write-spec");
 const read_specs_1 = require("./tools/read-specs");
+const ingest_source_1 = require("./tools/ingest-source");
+const update_index_1 = require("./tools/update-index");
+const list_wiki_1 = require("./tools/list-wiki");
+const wiki_search_1 = require("./tools/wiki-search");
+const answer_synthesis_1 = require("./tools/answer-synthesis");
+const query_wiki_1 = require("./tools/query-wiki");
+const save_answer_as_page_1 = require("./tools/save-answer-as-page");
+const lint_wiki_1 = require("./tools/lint-wiki");
+const get_schema_guidance_1 = require("./tools/get-schema-guidance");
+const preview_generation_1 = require("./tools/preview-generation");
 const server = new index_js_1.Server({ name: "docuflow", version: "0.1.0" }, { capabilities: { tools: {} } });
 server.setRequestHandler(types_js_1.ListToolsRequestSchema, async () => ({
     tools: [
@@ -66,6 +76,170 @@ server.setRequestHandler(types_js_1.ListToolsRequestSchema, async () => ({
                 required: ["project_path"],
             },
         },
+        {
+            name: "ingest_source",
+            description: "Ingest a markdown source document from .docuflow/sources/ and generate wiki pages (entities, concepts) with cross-references. Returns pages created and entities discovered.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    project_path: { type: "string", description: "Root of the project." },
+                    source_filename: {
+                        type: "string",
+                        description: "Filename in .docuflow/sources/ to ingest (e.g., 'overview.md').",
+                    },
+                },
+                required: ["project_path", "source_filename"],
+            },
+        },
+        {
+            name: "update_index",
+            description: "Scan all wiki pages in .docuflow/wiki/ and regenerate .docuflow/index.md organized by category. Appends operation to log.md.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    project_path: { type: "string", description: "Root of the project." },
+                },
+                required: ["project_path"],
+            },
+        },
+        {
+            name: "list_wiki",
+            description: "List all wiki pages in .docuflow/wiki/, optionally filtered by category. Returns metadata (title, created_at, sources, tags) and page counts by category.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    project_path: { type: "string", description: "Root of the project." },
+                    category: {
+                        type: "string",
+                        enum: ["entity", "concept", "timeline", "synthesis"],
+                        description: "Optional: filter to a specific category.",
+                    },
+                },
+                required: ["project_path"],
+            },
+        },
+        {
+            name: "wiki_search",
+            description: "Search the wiki for pages matching a query using relevance scoring. Returns ranked results with preview snippets and matched terms. BM25-inspired ranking weights entity pages higher.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    project_path: { type: "string", description: "Root of the project." },
+                    query: { type: "string", description: "Search query (e.g., 'MCP protocol design')." },
+                    limit: {
+                        type: "number",
+                        description: "Optional: max results to return (default: 10).",
+                    },
+                    category: {
+                        type: "string",
+                        enum: ["entity", "concept", "timeline", "synthesis"],
+                        description: "Optional: filter to a specific category.",
+                    },
+                },
+                required: ["project_path", "query"],
+            },
+        },
+        {
+            name: "synthesize_answer",
+            description: "Generate a synthesis answer from multiple wiki pages. Extracts relevant sentences, key concepts, and builds a markdown answer with citations.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    project_path: { type: "string", description: "Root of the project." },
+                    query: { type: "string", description: "The question being answered." },
+                    source_page_ids: {
+                        type: "array",
+                        items: { type: "string" },
+                        description: "List of wiki page IDs to synthesize from.",
+                    },
+                },
+                required: ["project_path", "query", "source_page_ids"],
+            },
+        },
+        {
+            name: "query_wiki",
+            description: "Ask a question against the wiki. Automatically searches for relevant pages, synthesizes an answer, and returns source pages with confidence score. One-stop tool for querying accumulated knowledge.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    project_path: { type: "string", description: "Root of the project." },
+                    question: { type: "string", description: "The question to ask (e.g., 'How does the MCP protocol work?')." },
+                    max_sources: {
+                        type: "number",
+                        description: "Optional: max source pages to use in synthesis (default: 5).",
+                    },
+                },
+                required: ["project_path", "question"],
+            },
+        },
+        {
+            name: "save_answer_as_page",
+            description: "Save a generated answer as a new wiki page. Allows query results to compound back into the knowledge base, growing the wiki with new synthesis pages. Automatically adds frontmatter and updates log.md.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    project_path: { type: "string", description: "Root of the project." },
+                    question: { type: "string", description: "The original question that was answered." },
+                    answer: { type: "string", description: "The markdown answer text to save." },
+                    page_title: { type: "string", description: "Title for the new page (e.g., 'How MCP Protocol Works')." },
+                    category: {
+                        type: "string",
+                        enum: ["synthesis", "entity", "concept", "timeline"],
+                        description: "Optional: wiki category for the page (default: synthesis).",
+                    },
+                    source_page_ids: {
+                        type: "array",
+                        items: { type: "string" },
+                        description: "Optional: list of source wiki page IDs used to generate this answer.",
+                    },
+                },
+                required: ["project_path", "question", "answer", "page_title"],
+            },
+        },
+        {
+            name: "lint_wiki",
+            description: "Health check wiki for quality issues: orphan pages, broken references, stale content, metadata gaps, and contradictions. Returns issues found, metrics, health score, and recommendations.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    project_path: { type: "string", description: "Root of the project." },
+                    check_type: {
+                        type: "string",
+                        enum: ["all", "orphans", "contradictions", "stale", "metadata"],
+                        description: "Optional: type of check to run (default: all).",
+                    },
+                },
+                required: ["project_path"],
+            },
+        },
+        {
+            name: "get_schema_guidance",
+            description: "Analyze what documents should exist based on project schema and current wiki. Removes decision fatigue by suggesting what to create next.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    project_path: { type: "string", description: "Root of the project." },
+                    domain: {
+                        type: "string",
+                        description: "Optional: domain hint (Code/Architecture, Research, Business, Personal). Auto-detected if not provided.",
+                    },
+                },
+                required: ["project_path"],
+            },
+        },
+        {
+            name: "preview_generation",
+            description: "Preview what a tool will generate before running it. Removes black-box feeling by showing predicted actions, outputs, and impact.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    tool_name: { type: "string", description: "Name of the tool to preview (e.g., ingest_source, query_wiki)." },
+                    project_path: { type: "string", description: "Root of the project." },
+                    params: { type: "object", description: "Parameters you would pass to that tool." },
+                },
+                required: ["tool_name", "project_path", "params"],
+            },
+        },
     ],
 }));
 server.setRequestHandler(types_js_1.CallToolRequestSchema, async (request) => {
@@ -84,6 +258,36 @@ server.setRequestHandler(types_js_1.CallToolRequestSchema, async (request) => {
         else if (name === "read_specs") {
             result = await (0, read_specs_1.readSpecs)(args);
         }
+        else if (name === "ingest_source") {
+            result = await (0, ingest_source_1.ingestSource)(args);
+        }
+        else if (name === "update_index") {
+            result = await (0, update_index_1.updateIndex)(args);
+        }
+        else if (name === "list_wiki") {
+            result = await (0, list_wiki_1.listWiki)(args);
+        }
+        else if (name === "wiki_search") {
+            result = await (0, wiki_search_1.wikiSearch)(args);
+        }
+        else if (name === "synthesize_answer") {
+            result = await (0, answer_synthesis_1.synthesizeAnswer)(args);
+        }
+        else if (name === "query_wiki") {
+            result = await (0, query_wiki_1.queryWiki)(args);
+        }
+        else if (name === "save_answer_as_page") {
+            result = await (0, save_answer_as_page_1.saveAnswerAsPage)(args);
+        }
+        else if (name === "lint_wiki") {
+            result = await (0, lint_wiki_1.lintWiki)(args);
+        }
+        else if (name === "get_schema_guidance") {
+            result = await (0, get_schema_guidance_1.getSchemataGuidance)(args);
+        }
+        else if (name === "preview_generation") {
+            result = await (0, preview_generation_1.previewGeneration)(args);
+        }
         else {
             result = { error: `Unknown tool: ${name}` };
         }

package/dist/tools/answer-synthesis.js

@@ -0,0 +1,189 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.synthesizeAnswer = synthesizeAnswer;
+const node_path_1 = __importDefault(require("node:path"));
+const filesystem_1 = require("../filesystem");
+/**
+ * Extract key sentences from content that relate to the query
+ */
+function extractRelevantSentences(content, queryTerms, maxSentences = 3) {
+    const sentences = content
+        .split(/[.!?]+/)
+        .map((s) => s.trim())
+        .filter((s) => s.length > 10 && !s.startsWith("#") && !s.startsWith("---"));
+    const scoredSentences = [];
+    for (const sentence of sentences) {
+        let score = 0;
+        const sentenceLower = sentence.toLowerCase();
+        for (const term of queryTerms) {
+            if (sentenceLower.includes(term)) {
+                // Count occurrences
+                const matches = sentenceLower.split(term).length - 1;
+                score += matches * 2;
+            }
+        }
+        if (score > 0) {
+            scoredSentences.push({ text: sentence, score });
+        }
+    }
+    // Sort by score and take top N
+    return scoredSentences
+        .sort((a, b) => b.score - a.score)
+        .slice(0, maxSentences)
+        .map((s) => s.text);
+}
+/**
+ * Extract key concepts from page content (from H3 headers, bold text)
+ */
+function extractKeyConcepts(content) {
+    const concepts = new Set();
+    // Extract from H3 headers
+    const h3Matches = content.matchAll(/^###\s+(.+?)$/gm);
+    for (const match of h3Matches) {
+        const concept = match[1].trim();
+        if (concept && concept.length < 80) {
+            concepts.add(concept);
+        }
+    }
+    // Extract from bold text (but not arrays/JSON)
+    const boldMatches = content.matchAll(/\*\*([^*]+)\*\*/g);
+    for (const match of boldMatches) {
+        const text = match[1].trim();
+        if (text.length > 3 &&
+            text.length < 60 &&
+            !text.includes("[") &&
+            !text.includes("{") &&
+            !text.includes('"')) {
+            concepts.add(text);
+        }
+    }
+    return Array.from(concepts).slice(0, 5);
+}
+/**
+ * Build a synthesis answer from multiple source pages
+ */
+function buildSynthesis(query, sourcePages, queryTerms) {
+    if (!sourcePages.length) {
+        return {
+            answer: `No information found related to: ${query}`,
+            concepts: [],
+        };
+    }
+    const allConcepts = new Set();
+    const sections = [];
+    // Add introduction
+    sections.push(`## Synthesis: ${query}\n`);
+    sections.push(`Based on ${sourcePages.length} source page(s):\n`);
+    // Add content from each source
+    for (const page of sourcePages) {
+        sections.push(`### ${page.title}`);
+        sections.push(`*Category: ${page.category} | Relevance: ${Math.round(page.relevance * 100)}%*\n`);
+        // Extract relevant sentences
+        const relevantSentences = extractRelevantSentences(page.content, queryTerms, 2);
+        if (relevantSentences.length > 0) {
+            sections.push(relevantSentences.map((s) => `- ${s.trim()}`).join("\n"));
+        }
+        else {
+            // Fallback: use first paragraph
+            const firstPara = page.content
+                .split("\n")
+                .filter((l) => l.trim() && !l.startsWith("#") && !l.startsWith("---"))
+                .slice(0, 1);
+            sections.push(firstPara.join("\n"));
+        }
+        // Collect concepts
+        const pageConcepts = extractKeyConcepts(page.content);
+        pageConcepts.forEach((c) => allConcepts.add(c));
+        sections.push("");
+    }
+    // Add summary
+    sections.push("\n## Key Concepts Found");
+    Array.from(allConcepts).forEach((c) => {
+        sections.push(`- ${c}`);
+    });
+    sections.push("\n## How to Extend This\n");
+    sections.push(`This synthesis was generated from ${sourcePages.length} page(s) containing the key terms: `);
+    sections.push(queryTerms.join(", "));
+    sections.push("\n\nAdd more source pages to deepen this synthesis.");
+    return {
+        answer: sections.join("\n"),
+        concepts: Array.from(allConcepts),
+    };
+}
+async function synthesizeAnswer(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");
+        // Load each source page
+        const sourcePages = [];
+        for (const pageId of input.source_page_ids) {
+            // Try to find the page (scan all category directories)
+            let found = false;
+            for (const categoryDir of ["entities", "concepts", "timelines", "syntheses"]) {
+                const filePath = node_path_1.default.join(wikiDir, categoryDir, `${pageId}.md`);
+                try {
+                    const read = await (0, filesystem_1.safeReadFile)(filePath);
+                    if (!read.error && !read.binary && read.content) {
+                        const titleMatch = read.content.match(/^#\s+(.+?)$/m);
+                        const title = titleMatch ? titleMatch[1].trim() : pageId;
+                        const category = categoryDir.replace("s", "");
+                        sourcePages.push({
+                            page_id: pageId,
+                            title,
+                            category,
+                            content: read.content,
+                            relevance: 1.0 - (sourcePages.length * 0.1), // Slight decay for order
+                        });
+                        found = true;
+                        break;
+                    }
+                }
+                catch (e) {
+                    // Try next category
+                }
+            }
+            if (!found && sourcePages.length === 0) {
+                // At least one page should be found
+                return {
+                    query: input.query,
+                    answer: `Could not find source page: ${pageId}`,
+                    source_pages: [],
+                    confidence: 0,
+                    key_concepts: [],
+                    error: `Page not found: ${pageId}`,
+                };
+            }
+        }
+        // Build query terms
+        const queryTerms = input.query.toLowerCase().split(/\s+/).filter((t) => t.length > 2);
+        // Generate synthesis
+        const { answer, concepts } = buildSynthesis(input.query, sourcePages, queryTerms);
+        // Calculate confidence based on number and relevance of sources
+        const confidence = Math.min(1.0, Math.max(0.3, sourcePages.length * 0.25));
+        return {
+            query: input.query,
+            answer,
+            source_pages: sourcePages.map((p) => ({
+                page_id: p.page_id,
+                title: p.title,
+                category: p.category,
+            })),
+            confidence,
+            key_concepts: concepts,
+        };
+    }
+    catch (e) {
+        return {
+            query: input.query,
+            answer: `Error synthesizing answer: ${e?.message ?? String(e)}`,
+            source_pages: [],
+            confidence: 0,
+            key_concepts: [],
+            error: e?.message ?? String(e),
+        };
+    }
+}

package/dist/tools/get-schema-guidance.js

@@ -0,0 +1,213 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getSchemataGuidance = getSchemataGuidance;
+const node_path_1 = __importDefault(require("node:path"));
+const promises_1 = __importDefault(require("node:fs/promises"));
+/**
+ * get_schema_guidance
+ *
+ * Analyzes what documents should exist based on the project schema and current wiki state.
+ * Helps users understand what to create next.
+ *
+ * Input:
+ * - project_path: string
+ * - domain?: string (optional; auto-detected from schema if not provided)
+ *
+ * Output:
+ * - domain: detected domain
+ * - recommended_pages: list of pages that should exist with reasons
+ * - existing_pages: what's already in the wiki
+ * - missing_pages: high-priority missing documents
+ * - recommendations: actionable next steps
+ */
+async function getSchemataGuidance(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 schemaPath = node_path_1.default.join(docuDir, "schema.md");
+    // Read schema to understand domain
+    let domain = input.domain || "General";
+    try {
+        const schemaContent = await promises_1.default.readFile(schemaPath, "utf-8");
+        if (schemaContent.includes("Research"))
+            domain = "Research";
+        else if (schemaContent.includes("Business"))
+            domain = "Business";
+        else if (schemaContent.includes("Architecture"))
+            domain = "Code/Architecture";
+        else if (schemaContent.includes("Personal"))
+            domain = "Personal";
+    }
+    catch {
+        // Use default if schema not readable
+    }
+    // Scan wiki for existing pages
+    const indexPath = node_path_1.default.join(docuDir, "index.md");
+    const indexContent = await promises_1.default
+        .readFile(indexPath, "utf-8")
+        .catch(() => "");
+    // Count pages by category
+    const existingPages = [];
+    const categories = ["entities", "concepts", "syntheses", "timelines"];
+    for (const cat of categories) {
+        const catDir = node_path_1.default.join(wikiDir, cat);
+        try {
+            const files = await promises_1.default.readdir(catDir);
+            for (const file of files.filter((f) => f.endsWith(".md"))) {
+                existingPages.push({
+                    name: file.replace(".md", ""),
+                    category: cat,
+                });
+            }
+        }
+        catch {
+            // Directory may not exist
+        }
+    }
+    // Define recommended pages by domain
+    const recommendedByDomain = {
+        "Code/Architecture": [
+            {
+                name: "architecture_overview",
+                category: "syntheses",
+                suggested_title: "System Architecture Overview",
+                reason: "High-level view of how all components fit together",
+            },
+            {
+                name: "core_patterns",
+                category: "concepts",
+                suggested_title: "Core Architectural Patterns",
+                reason: "Design patterns used throughout the codebase",
+            },
+            {
+                name: "module_dependencies",
+                category: "concepts",
+                suggested_title: "Module Dependencies",
+                reason: "How modules depend on and integrate with each other",
+            },
+            {
+                name: "data_flow",
+                category: "syntheses",
+                suggested_title: "Data Flow Diagram",
+                reason: "How data moves through the system",
+            },
+        ],
+        Research: [
+            {
+                name: "research_overview",
+                category: "syntheses",
+                suggested_title: "Research Domain Overview",
+                reason: "Big picture of the research area",
+            },
+            {
+                name: "key_findings",
+                category: "syntheses",
+                suggested_title: "Key Findings & Synthesis",
+                reason: "Major discoveries and insights",
+            },
+            {
+                name: "contradictions",
+                category: "syntheses",
+                suggested_title: "Areas of Contradiction",
+                reason: "Where researchers disagree",
+            },
+            {
+                name: "open_questions",
+                category: "concepts",
+                suggested_title: "Open Research Questions",
+                reason: "What's still unknown in this domain",
+            },
+        ],
+        Business: [
+            {
+                name: "market_overview",
+                category: "syntheses",
+                suggested_title: "Market Overview",
+                reason: "Big picture of the market and competitive landscape",
+            },
+            {
+                name: "competitive_analysis",
+                category: "syntheses",
+                suggested_title: "Competitive Analysis",
+                reason: "Comparison of key competitors",
+            },
+            {
+                name: "opportunities",
+                category: "syntheses",
+                suggested_title: "Market Opportunities",
+                reason: "Gaps and growth areas",
+            },
+            {
+                name: "risks",
+                category: "concepts",
+                suggested_title: "Market Risks",
+                reason: "Threats and challenges",
+            },
+        ],
+        Personal: [
+            {
+                name: "learning_goals",
+                category: "concepts",
+                suggested_title: "Learning Goals",
+                reason: "What you want to learn in this domain",
+            },
+            {
+                name: "key_insights",
+                category: "syntheses",
+                suggested_title: "Key Personal Insights",
+                reason: "Major learnings and takeaways",
+            },
+            {
+                name: "action_items",
+                category: "concepts",
+                suggested_title: "Action Items & Next Steps",
+                reason: "What to do with this knowledge",
+            },
+            {
+                name: "resources",
+                category: "concepts",
+                suggested_title: "Key Resources",
+                reason: "Important links, books, people",
+            },
+        ],
+    };
+    const recommended = recommendedByDomain[domain] || recommendedByDomain.General;
+    // Find missing pages
+    const missingPages = [];
+    for (const rec of recommended) {
+        const found = existingPages.find((p) => p.name === rec.name);
+        if (!found) {
+            missingPages.push(rec.suggested_title);
+        }
+    }
+    // Generate recommendations
+    const recommendations = [];
+    if (existingPages.length === 0) {
+        recommendations.push("🌱 Start by ingesting your first source");
+        recommendations.push("📝 Create an overview/synthesis page");
+    }
+    else if (existingPages.length < 10) {
+        recommendations.push("📚 Add more sources to deepen understanding");
+        if (missingPages.length > 0) {
+            recommendations.push(`⚠️ Consider creating: ${missingPages[0]}`);
+        }
+    }
+    else if (existingPages.length > 50) {
+        recommendations.push("✅ You have a solid wiki foundation");
+        recommendations.push("🔍 Run lint_wiki to health-check for gaps");
+        recommendations.push("🔗 Verify cross-references are accurate");
+    }
+    if (missingPages.length > 2) {
+        recommendations.push(`💡 Biggest gap: ${missingPages[0]} could improve wiki significantly`);
+    }
+    return {
+        domain,
+        recommended_pages: recommended,
+        existing_pages: existingPages,
+        missing_pages: missingPages,
+        recommendations,
+    };
+}