@doquflow/server 1.7.0 → 2.0.0

package/dist/tools/list-wiki.js

@@ -1,198 +0,0 @@
-"use strict";
-var __importDefault = (this && this.__importDefault) || function (mod) {
-    return (mod && mod.__esModule) ? mod : { "default": mod };
-};
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.listWiki = listWiki;
-const node_path_1 = __importDefault(require("node:path"));
-const promises_1 = __importDefault(require("node:fs/promises"));
-const filesystem_1 = require("../filesystem");
-const PLURAL_TO_SINGULAR = {
-    entities: "entity",
-    concepts: "concept",
-    timelines: "timeline",
-    syntheses: "synthesis",
-};
-const SINGULAR_TO_PLURAL = {
-    entity: "entities",
-    concept: "concepts",
-    timeline: "timelines",
-    synthesis: "syntheses",
-};
-const STALE_DAYS = 30;
-function unquote(s) {
-    const t = s.trim();
-    if (t.length >= 2) {
-        const first = t[0];
-        const last = t[t.length - 1];
-        if ((first === '"' && last === '"') || (first === "'" && last === "'")) {
-            return t.slice(1, -1);
-        }
-    }
-    return t;
-}
-/**
- * Parse YAML-ish frontmatter from markdown.
- *
- * Supports:
- *   - Inline JSON/flow:  key: ["a", "b"]   or   key: {x: 1}
- *   - Block-style list:  key:\n  - "a"\n  - "b"
- *   - Scalar:            key: value (values may contain ':' — split on FIRST ':' only)
- */
-function parseFrontmatter(content) {
-    const match = content.match(/^---\n([\s\S]*?)\n---/);
-    if (!match)
-        return {};
-    const lines = match[1].split("\n");
-    const result = {};
-    let i = 0;
-    while (i < lines.length) {
-        const line = lines[i];
-        const trimmed = line.trim();
-        if (!trimmed) {
-            i++;
-            continue;
-        }
-        // Block-list continuation handled inside the key branch below; top-level
-        // dashes without a preceding key are ignored.
-        if (trimmed.startsWith("- ")) {
-            i++;
-            continue;
-        }
-        const colonIdx = line.indexOf(":");
-        if (colonIdx === -1) {
-            i++;
-            continue;
-        }
-        const key = line.slice(0, colonIdx).trim();
-        const rawValue = line.slice(colonIdx + 1).trim();
-        if (rawValue === "") {
-            // Possibly a block-style list on subsequent lines: "  - value"
-            const items = [];
-            let j = i + 1;
-            while (j < lines.length) {
-                const next = lines[j];
-                if (!next.trim()) {
-                    j++;
-                    continue;
-                }
-                // A block-list item must be indented and start with "- ".
-                const m = next.match(/^(\s+)-\s+(.*)$/);
-                if (!m)
-                    break;
-                items.push(unquote(m[2]));
-                j++;
-            }
-            if (items.length > 0) {
-                result[key] = items;
-            }
-            else {
-                result[key] = "";
-            }
-            i = j;
-            continue;
-        }
-        if (rawValue.startsWith("[") || rawValue.startsWith("{")) {
-            try {
-                result[key] = JSON.parse(rawValue);
-            }
-            catch {
-                result[key] = rawValue;
-            }
-        }
-        else {
-            result[key] = unquote(rawValue);
-        }
-        i++;
-    }
-    return result;
-}
-function toStringArray(v) {
-    if (!Array.isArray(v))
-        return [];
-    return v.filter((x) => typeof x === "string");
-}
-/**
- * Extract title from markdown
- */
-function extractTitle(content) {
-    const match = content.match(/^#\s+(.+?)$/m);
-    return match ? match[1].trim() : "Untitled";
-}
-async function listWiki(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 pages = [];
-        const categories = {};
-        const now = Date.now();
-        // Build list of categories to scan — always use correct plural directory names
-        let categoriesToScan = ["entities", "concepts", "timelines", "syntheses"];
-        if (input.category) {
-            const pluralDir = SINGULAR_TO_PLURAL[input.category] ?? `${input.category}s`;
-            categoriesToScan = [pluralDir];
-        }
-        // Scan each category
-        for (const categoryDir of categoriesToScan) {
-            const fullCategoryPath = node_path_1.default.join(wikiDir, categoryDir);
-            const category = PLURAL_TO_SINGULAR[categoryDir] ?? categoryDir;
-            try {
-                const files = await promises_1.default.readdir(fullCategoryPath);
-                let categoryCount = 0;
-                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;
-                    const fm = parseFrontmatter(read.content);
-                    const title = extractTitle(read.content);
-                    const pageId = file.replace(".md", "");
-                    const updatedAt = fm.updated_at ?? new Date().toISOString();
-                    const updatedMs = new Date(updatedAt).getTime();
-                    const stale = !isNaN(updatedMs) && (now - updatedMs) > STALE_DAYS * 86_400_000;
-                    const outbound_links = toStringArray(fm.outbound_links);
-                    const inbound_links = toStringArray(fm.inbound_links);
-                    pages.push({
-                        id: pageId,
-                        title,
-                        category,
-                        path: node_path_1.default.relative(docuDir, filePath),
-                        created_at: fm.created_at ?? new Date().toISOString(),
-                        updated_at: updatedAt,
-                        sources: toStringArray(fm.sources),
-                        tags: toStringArray(fm.tags),
-                        stale,
-                        outbound_links,
-                        inbound_links,
-                        degree: outbound_links.length + inbound_links.length,
-                    });
-                    categoryCount++;
-                }
-                if (categoryCount > 0) {
-                    categories[category] = categoryCount;
-                }
-            }
-            catch (e) {
-                // Category directory may not exist yet
-            }
-        }
-        return {
-            total_pages: pages.length,
-            stale_pages: pages.filter((p) => p.stale).length,
-            pages: pages.sort((a, b) => a.title.localeCompare(b.title)),
-            categories,
-        };
-    }
-    catch (e) {
-        return {
-            total_pages: 0,
-            stale_pages: 0,
-            pages: [],
-            categories: {},
-            error: e?.message ?? String(e),
-        };
-    }
-}

package/dist/tools/preview-generation.js

@@ -1,228 +0,0 @@
-"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

@@ -1,67 +0,0 @@
-"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-module.js

@@ -1,53 +0,0 @@
-"use strict";
-var __importDefault = (this && this.__importDefault) || function (mod) {
-    return (mod && mod.__esModule) ? mod : { "default": mod };
-};
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.readModule = readModule;
-const node_path_1 = __importDefault(require("node:path"));
-const filesystem_1 = require("../filesystem");
-const language_map_1 = require("../language-map");
-const extractor_1 = require("../extractor");
-const MAX_RAW = 8000;
-async function readModule(input) {
-    const filePath = node_path_1.default.resolve(input.path);
-    const language = (0, language_map_1.extensionToLanguage)(filePath);
-    const read = await (0, filesystem_1.safeReadFile)(filePath);
-    if (read.error) {
-        return {
-            path: filePath,
-            language,
-            size_bytes: 0,
-            classes: [],
-            functions: [],
-            dependencies: [],
-            db_tables: [],
-            endpoints: [],
-            config_refs: [],
-            error: read.error,
-        };
-    }
-    if (read.binary) {
-        return {
-            path: filePath,
-            language,
-            size_bytes: read.size,
-            classes: [],
-            functions: [],
-            dependencies: [],
-            db_tables: [],
-            endpoints: [],
-            config_refs: [],
-            error: "binary file skipped",
-        };
-    }
-    const content = read.content ?? "";
-    const facts = (0, extractor_1.extract)(content);
-    return {
-        path: filePath,
-        language,
-        size_bytes: read.size,
-        ...facts,
-        raw_content: content.length > MAX_RAW ? content.slice(0, MAX_RAW) : content,
-    };
-}

package/dist/tools/read-specs.js

@@ -1,39 +0,0 @@
-"use strict";
-var __importDefault = (this && this.__importDefault) || function (mod) {
-    return (mod && mod.__esModule) ? mod : { "default": mod };
-};
-Object.defineProperty(exports, "__esModule", { value: true });
-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");
-    const indexPath = node_path_1.default.join(docuDir, "index.json");
-    const index = await (0, filesystem_1.readJsonIfExists)(indexPath);
-    if (!index || index.specs.length === 0) {
-        return { specs_found: 0, specs: [] };
-    }
-    let entries = index.specs;
-    if (input.module_name) {
-        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");
-            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
-        }
-    }
-    return { specs_found: specs.length, specs };
-}

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

@@ -1,91 +0,0 @@
-"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");
-const category_dir_1 = require("../category-dir");
-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");
-        const category = input.category ?? "synthesis";
-        const catDirPath = node_path_1.default.join(wikiDir, (0, category_dir_1.categoryDir)(category));
-        await (0, filesystem_1.ensureDir)(catDirPath);
-        const pageId = `query_${input.page_title
-            .toLowerCase()
-            .replace(/[^a-z0-9]/g, "_")
-            .replace(/_+/g, "_")
-            .substring(0, 50)}`;
-        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 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}\`](../${(0, category_dir_1.categoryDir)(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.*
-`;
-        const pageFile = node_path_1.default.join(catDirPath, `${pageId}.md`);
-        await (0, filesystem_1.writeFileAtomic)(pageFile, pageContent);
-        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];
-            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),
-        };
-    }
-}