@doquflow/cli 1.6.0 → 1.7.0

package/dist/commands/help.js

@@ -0,0 +1,37 @@
+"use strict";
+// Help text for `docuflow --help` and `docuflow advanced --help`.
+// No external help library — plain console.log for zero-dependency output.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.printCoreHelp = printCoreHelp;
+exports.printAdvancedHelp = printAdvancedHelp;
+function printCoreHelp() {
+    console.log('DocuFlow — preserve decision context for AI agents.');
+    console.log('');
+    console.log('CORE');
+    console.log('  docuflow init                         Initialise .docuflow/ in this project');
+    console.log('  docuflow ingest <file>                Add a source document to the wiki');
+    console.log('  docuflow query "<question>"           Ask the wiki — answer with citations');
+    console.log('  docuflow status                       Show wiki health and counts');
+    console.log('  docuflow rewiki                       Migrate / re-ingest with current rules');
+    console.log('');
+    console.log('ADVANCED');
+    console.log('  docuflow advanced --help              See watch / sync / ui / review / recent / suggest / update');
+    console.log('');
+    console.log('  docuflow --version                    Print version');
+    console.log('  docuflow --help                       Show this help');
+}
+function printAdvancedHelp() {
+    console.log('DocuFlow — advanced surface (sync daemons, UI, audit commands).');
+    console.log('');
+    console.log('  docuflow advanced watch [stop|status|restart]    Auto-sync daemon');
+    console.log('  docuflow advanced sync [--ai]                    One-shot sync for CI / git hooks');
+    console.log('  docuflow advanced ui [--port N]                  Launch web UI dashboard');
+    console.log('  docuflow advanced start                          Alias for ui');
+    console.log('  docuflow advanced review                         Review uncommitted changes');
+    console.log('  docuflow advanced recent                         Recent work dashboard');
+    console.log('  docuflow advanced suggest                        First-steps guidance');
+    console.log('  docuflow advanced update                         Self-upgrade DocuFlow');
+    console.log('');
+    console.log('Note: every "advanced" command also works at its old top-level path');
+    console.log('(e.g. `docuflow watch` is still valid). The "advanced" prefix is optional.');
+}

package/dist/commands/ingest.js

@@ -0,0 +1,115 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.run = run;
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const c = {
+    green: (s) => `\x1b[32m${s}\x1b[0m`,
+    yellow: (s) => `\x1b[33m${s}\x1b[0m`,
+    red: (s) => `\x1b[31m${s}\x1b[0m`,
+    cyan: (s) => `\x1b[36m${s}\x1b[0m`,
+    dim: (s) => `\x1b[2m${s}\x1b[0m`,
+    bold: (s) => `\x1b[1m${s}\x1b[0m`,
+};
+function loadServerTool(toolFile) {
+    const candidates = [
+        () => require(`@doquflow/server/dist/tools/${toolFile}`),
+        () => require(node_path_1.default.resolve(__dirname, "../../../server/dist/tools", toolFile)),
+        () => require(node_path_1.default.resolve(__dirname, "../../server/dist/tools", toolFile)),
+    ];
+    for (const attempt of candidates) {
+        try {
+            return attempt();
+        }
+        catch { }
+    }
+    throw new Error(`Cannot load server tool "${toolFile}". Run "npm run build" first.`);
+}
+async function run(options) {
+    const { sourceFile, all = false, dryRun = false, quiet = false } = options;
+    const projectPath = node_path_1.default.resolve(process.cwd());
+    const docuDir = node_path_1.default.join(projectPath, ".docuflow");
+    const sourcesDir = node_path_1.default.join(docuDir, "sources");
+    function info(msg) { if (!quiet)
+        process.stdout.write(msg + "\n"); }
+    if (!all && !sourceFile) {
+        console.error(c.red("  ✗ Provide a source filename or pass --all."));
+        console.error(`    Usage: docuflow ingest <source.md>`);
+        console.error(`           docuflow ingest --all`);
+        process.exit(2);
+    }
+    if (!node_fs_1.default.existsSync(docuDir)) {
+        console.error(c.red(`  ✗ .docuflow/ not found at ${projectPath}`));
+        console.error(`    Run "docuflow init" first.`);
+        process.exit(2);
+    }
+    if (dryRun) {
+        info(c.yellow("  dry-run not supported for ingest_source; use `docuflow rewiki --dry-run` for a full simulation"));
+        process.exit(0);
+    }
+    let ingestSource;
+    try {
+        ({ ingestSource } = loadServerTool("ingest-source"));
+    }
+    catch (e) {
+        console.error(c.red(`  ✗ ${e.message}`));
+        process.exit(2);
+    }
+    // Collect files to ingest
+    let files;
+    if (all) {
+        if (!node_fs_1.default.existsSync(sourcesDir)) {
+            console.error(c.yellow("  No .docuflow/sources/ directory found — nothing to ingest."));
+            process.exit(0);
+        }
+        files = node_fs_1.default.readdirSync(sourcesDir).filter(f => f.endsWith(".md"));
+        if (files.length === 0) {
+            info(c.yellow("  No source files found in .docuflow/sources/"));
+            process.exit(0);
+        }
+    }
+    else {
+        // Single file — verify it exists
+        const filename = sourceFile;
+        const fullPath = node_path_1.default.join(sourcesDir, filename);
+        if (!node_fs_1.default.existsSync(fullPath)) {
+            console.error(c.red(`  ✗ Source file not found: .docuflow/sources/${filename}`));
+            process.exit(3);
+        }
+        files = [filename];
+    }
+    info(c.bold(`DocuFlow ingest`));
+    info(`  Project : ${projectPath}`);
+    info(`  Files   : ${files.length}`);
+    info("");
+    let totalCreated = 0;
+    let totalUpdated = 0;
+    let errored = 0;
+    for (const filename of files) {
+        info(c.dim(`  Ingesting ${filename}…`));
+        try {
+            const result = await ingestSource({ project_path: projectPath, source_filename: filename });
+            totalCreated += result.pages_created ?? 0;
+            totalUpdated += result.pages_updated ?? 0;
+            info(`  ${c.green("✓")} ${filename}` +
+                `  ${c.dim(`+${result.pages_created ?? 0} created, ~${result.pages_updated ?? 0} updated`)}`);
+        }
+        catch (e) {
+            errored++;
+            console.error(c.red(`  ✗ ${filename}: ${e.message}`));
+        }
+    }
+    info("");
+    if (errored === 0) {
+        info(c.green("  ✓ Done.") +
+            `  Pages created: ${totalCreated}  updated: ${totalUpdated}`);
+    }
+    else {
+        info(c.yellow(`  Done with ${errored} error(s).`) +
+            `  Pages created: ${totalCreated}  updated: ${totalUpdated}`);
+        process.exit(2);
+    }
+}

package/dist/commands/init.js

@@ -101,64 +101,55 @@ async function copyTemplateFile(templateName, destPath) {
     }
 }
 function buildClaudeMd(projectDir) {
-    return `# DocuFlow — AI Documentation Assistant
-
-DocuFlow is an MCP server that gives you structured access to this codebase and maintains a living wiki.
-It is registered in your Claude Desktop config and available as MCP tools in every session.
-
-## Codebase Scanner Tools
+    return `<!-- BEGIN DOCUFLOW -->
+# DocuFlow — AI Documentation Assistant
 
-- **read_module** — Analyse a single source file. Returns language, classes, functions, dependencies, DB tables, endpoints, config refs, and raw content (first 8 KB).
-  - Example: \`read_module({ path: "src/UserService.cs" })\`
-- **list_modules** — Walk a directory and extract facts for every non-binary file. Use this to understand the full project in one call.
-  - Example: \`list_modules({ path: "${projectDir}" })\`
-- **write_spec** — Persist a markdown spec to \`.docuflow/specs/<filename>.md\` and update the index.
-  - Example: \`write_spec({ project_path: "${projectDir}", filename: "UserService", content: "# UserService\\n..." })\`
-- **read_specs** — Read previously written specs, optionally filtered by name.
-  - Example: \`read_specs({ project_path: "${projectDir}" })\`
+DocuFlow preserves decision context for AI agents. Intent in, value out.
 
-## Wiki Pipeline Tools
-
-- **ingest_source** — Ingest a markdown file from \`.docuflow/sources/\` and generate wiki pages (entities, concepts).
-- **update_index** — Rebuild \`.docuflow/index.md\` from all wiki pages.
-- **list_wiki** — List all wiki pages, optionally filtered by category (entity/concept/timeline/synthesis).
-- **wiki_search** — BM25 search across all wiki pages. Returns ranked results with previews.
-- **query_wiki** — One-stop Q&A: searches wiki, synthesises an answer, returns source citations.
-- **synthesize_answer** — Generate a markdown synthesis from a list of specific wiki page IDs.
-- **save_answer_as_page** — Persist a synthesised answer back into the wiki (knowledge compounding).
+## Core tools (use these first)
 
-## Health & Guidance Tools
+- **query_wiki({ project_path, question })** — Ask the wiki. Returns an answer with citations.
+- **ingest_source({ project_path, source_filename })** — Fold a markdown source into the wiki.
+- **wiki_search({ project_path, query })** — BM25 search across all pages.
+- **read_module({ path })** — Read and extract facts from a single source file.
 
-- **lint_wiki** — Health check: orphan pages, broken refs, stale content, metadata gaps. Returns a 0–100 health score.
-- **get_schema_guidance** — Analyse what wiki pages should exist based on the schema and current state.
-- **preview_generation** — Preview what a tool will do before running it.
+## CLI — Core Commands
 
-## Common Workflows
-
-### First time — understand the codebase
 \`\`\`
-list_modules({ path: "${projectDir}" })
-→ read the language breakdown and dependency map
-→ write_spec each important module
+docuflow query "<question>"         # ask the wiki from the shell
+docuflow ingest <source.md>         # add a source doc to the wiki
+docuflow status                     # wiki health and counts
+docuflow rewiki                     # re-ingest with current rules
+docuflow init                       # initialise .docuflow/ in this project
 \`\`\`
 
-### Ongoing — answer a question
+## Workflows
+
+### Answer a question
 \`\`\`
 query_wiki({ project_path: "${projectDir}", question: "How does authentication work?" })
-→ save_answer_as_page if the answer is worth keeping
 \`\`\`
 
-### Maintenance — check wiki health
+### Add new context
 \`\`\`
-lint_wiki({ project_path: "${projectDir}" })
-→ fix orphans and broken refs
+# drop a markdown file in .docuflow/sources/
+ingest_source({ project_path: "${projectDir}", source_filename: "auth-design.md" })
 \`\`\`
 
-### Maintenance — re-ingest with updated rules
-\`\`\`
-docuflow rewiki --dry-run   # preview cleanup
-docuflow rewiki             # apply (backs up wiki first)
-\`\`\`
+## Advanced tools
+
+Use when the core tools don't cover the workflow. Each has more parameters and side effects.
+
+- **list_modules** — Walk a directory tree and extract facts in bulk
+- **list_wiki** — Inventory pages by category, with staleness flags
+- **write_spec / read_specs** — Persistent agent-written specs
+- **save_answer_as_page** — Promote a synthesised answer into the wiki
+- **synthesize_answer** — Combine multiple pages into a markdown synthesis
+- **update_index** — Rebuild \`.docuflow/index.md\`
+- **lint_wiki** — Health checks: orphans, broken refs, stale content
+- **get_schema_guidance** — Recommend what pages should exist
+- **preview_generation** — Show what a tool will do before running
+- **generate_dependency_graph** — Build the import/shared-table graph
 
 ## Storage Layout
 
@@ -175,20 +166,25 @@ docuflow rewiki             # apply (backs up wiki first)
 ├── index.md         Auto-maintained catalog
 └── log.md           Operation log
 \`\`\`
-`;
+<!-- END DOCUFLOW -->`;
 }
 async function writeClaudeMd(projectDir) {
     const claudeMdPath = node_path_1.default.join(projectDir, "CLAUDE.md");
     const newSection = buildClaudeMd(projectDir);
     if (node_fs_1.default.existsSync(claudeMdPath)) {
         const existing = await promises_1.default.readFile(claudeMdPath, "utf8");
-        if (existing.includes("DocuFlow")) {
-            // Already has DocuFlow section — replace it
+        if (existing.includes("<!-- BEGIN DOCUFLOW -->") && existing.includes("<!-- END DOCUFLOW -->")) {
+            // Marker-based replacement — idempotent re-runs preserve surrounding content
+            const replaced = existing.replace(/<!-- BEGIN DOCUFLOW -->[\s\S]*?<!-- END DOCUFLOW -->/, newSection.trimEnd());
+            await promises_1.default.writeFile(claudeMdPath, replaced, "utf8");
+        }
+        else if (existing.includes("DocuFlow")) {
+            // Old format without markers — replace old DocuFlow section, add markers this time
             const withoutDocuflow = existing.replace(/\n?# DocuFlow[\s\S]*/, "").trimEnd();
             await promises_1.default.writeFile(claudeMdPath, withoutDocuflow + "\n\n" + newSection, "utf8");
         }
         else {
-            // Append to existing CLAUDE.md
+            // No DocuFlow section yet — append
             await promises_1.default.appendFile(claudeMdPath, "\n\n" + newSection, "utf8");
         }
     }

package/dist/commands/query.js

@@ -0,0 +1,141 @@
+"use strict";
+/**
+ * docuflow query
+ *
+ * Calls query_wiki and renders the answer with citations.
+ *
+ * Usage:
+ *   docuflow query "<question>"
+ *   docuflow query "<question>" --max-sources 5
+ *   docuflow query "<question>" --json
+ *   docuflow query "<question>" --no-cite
+ *   docuflow query "<question>" --save-as "<title>"
+ *   docuflow query "<question>" --quiet
+ *
+ * Exit codes:
+ *   0 — answer produced
+ *   2 — fatal (.docuflow missing, server tool not found)
+ *   3 — query produced no matching sources
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.run = run;
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+// ─── Colour helpers ────────────────────────────────────────────────────────────
+const c = {
+    green: (s) => `\x1b[32m${s}\x1b[0m`,
+    yellow: (s) => `\x1b[33m${s}\x1b[0m`,
+    red: (s) => `\x1b[31m${s}\x1b[0m`,
+    cyan: (s) => `\x1b[36m${s}\x1b[0m`,
+    dim: (s) => `\x1b[2m${s}\x1b[0m`,
+    bold: (s) => `\x1b[1m${s}\x1b[0m`,
+};
+// ─── Dynamic server tool loader (mirrors rewiki.ts pattern) ───────────────────
+function loadServerTool(toolFile) {
+    const candidates = [
+        () => require(`@doquflow/server/dist/tools/${toolFile}`),
+        () => require(node_path_1.default.resolve(__dirname, "../../../server/dist/tools", toolFile)),
+        () => require(node_path_1.default.resolve(__dirname, "../../server/dist/tools", toolFile)),
+    ];
+    for (const attempt of candidates) {
+        try {
+            return attempt();
+        }
+        catch { }
+    }
+    throw new Error(`Cannot load server tool "${toolFile}". Run "npm run build" first.`);
+}
+async function run(options) {
+    const { question, maxSources = 5, json = false, noCite = false, saveAs, quiet = false } = options;
+    const projectPath = node_path_1.default.resolve(process.cwd());
+    const docuDir = node_path_1.default.join(projectPath, ".docuflow");
+    function info(msg) { if (!quiet)
+        console.log(msg); }
+    // ── Validate question ───────────────────────────────────────────────────────
+    if (!question || question.trim() === "") {
+        console.error(c.red("  ✗ Question is required."));
+        console.error(`    Usage: docuflow query "<question>"`);
+        process.exit(2);
+    }
+    // ── Pre-flight ──────────────────────────────────────────────────────────────
+    if (!node_fs_1.default.existsSync(docuDir)) {
+        console.error(c.red(`  ✗ .docuflow/ not found at ${projectPath}`));
+        console.error(`    Run "docuflow init" first.`);
+        process.exit(2);
+    }
+    // ── Load tools ──────────────────────────────────────────────────────────────
+    let queryWiki;
+    let saveAnswerAsPage;
+    try {
+        ({ queryWiki } = loadServerTool("query-wiki"));
+        if (saveAs) {
+            ({ saveAnswerAsPage } = loadServerTool("save-answer-as-page"));
+        }
+    }
+    catch (e) {
+        console.error(c.red(`  ✗ ${e.message}`));
+        process.exit(2);
+    }
+    // ── Execute query ───────────────────────────────────────────────────────────
+    info(c.dim(`  Searching wiki for: "${question}"`));
+    let result;
+    try {
+        result = await queryWiki({ project_path: projectPath, question, max_sources: maxSources });
+    }
+    catch (e) {
+        console.error(c.red(`  ✗ Query failed: ${e.message}`));
+        process.exit(2);
+    }
+    if (result.error) {
+        console.error(c.red(`  ✗ ${result.error}`));
+        process.exit(2);
+    }
+    // ── No sources found ────────────────────────────────────────────────────────
+    if (!result.source_pages || result.source_pages.length === 0) {
+        if (!json) {
+            console.error(c.yellow("  No matching sources found in the wiki."));
+            console.error(`  Try running "docuflow rewiki" to rebuild the wiki first.`);
+        }
+        process.exit(3);
+    }
+    // ── Output ──────────────────────────────────────────────────────────────────
+    if (json) {
+        console.log(JSON.stringify({
+            question: result.question,
+            answer: result.answer,
+            source_pages: result.source_pages,
+            search_results: result.search_results,
+            confidence: result.confidence,
+        }, null, 2));
+    }
+    else if (noCite) {
+        console.log(result.answer);
+    }
+    else {
+        console.log(result.answer);
+        console.log("");
+        console.log(c.bold("## Sources"));
+        for (const page of result.source_pages) {
+            console.log(`  - ${page.title} ${c.dim("(" + page.page_id + ")")}`);
+        }
+    }
+    // ── Save ────────────────────────────────────────────────────────────────────
+    if (saveAs && saveAnswerAsPage) {
+        try {
+            const saved = await saveAnswerAsPage({
+                project_path: projectPath,
+                question,
+                answer: result.answer,
+                page_title: saveAs,
+                source_page_ids: (result.source_pages ?? []).map((p) => p.page_id),
+            });
+            process.stderr.write(`page-id: ${saved?.page_id ?? saveAs}\n`);
+        }
+        catch (e) {
+            process.stderr.write(c.red(`Warning: could not save page: ${e.message}\n`));
+        }
+    }
+}