@doquflow/cli 1.5.2 → 1.7.0

package/dist/commands/rewiki.js

@@ -0,0 +1,339 @@
+"use strict";
+/**
+ * docuflow rewiki
+ *
+ * Re-ingests all sources with the current extractor rules, migrates any
+ * synthesiss/ typo (defense-in-depth), backs up the existing wiki, and
+ * produces an audit report of removed / preserved pages.
+ *
+ * Usage:
+ *   docuflow rewiki                  # full migration with backup
+ *   docuflow rewiki --dry-run        # preview what would change, no writes
+ *   docuflow rewiki --no-backup      # skip backup (faster, irreversible)
+ *   docuflow rewiki --quiet          # suppress progress output
+ *
+ * Exit codes:
+ *   0 — success
+ *   2 — fatal error (.docuflow missing, server tools not found)
+ */
+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 promises_1 = __importDefault(require("node:fs/promises"));
+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 sync.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.`);
+}
+function parseTags(content) {
+    const m = content.match(/^tags:\s*(\[.*?\])/m);
+    if (!m)
+        return [];
+    try {
+        return JSON.parse(m[1]);
+    }
+    catch {
+        return [];
+    }
+}
+async function scanWiki(wikiDir) {
+    const pages = [];
+    if (!node_fs_1.default.existsSync(wikiDir))
+        return pages;
+    const subdirs = await promises_1.default.readdir(wikiDir).catch(() => []);
+    for (const subdir of subdirs) {
+        const subdirPath = node_path_1.default.join(wikiDir, subdir);
+        const stat = await promises_1.default.stat(subdirPath).catch(() => null);
+        if (!stat?.isDirectory())
+            continue;
+        const files = await promises_1.default.readdir(subdirPath).catch(() => []);
+        for (const file of files) {
+            if (!file.endsWith(".md"))
+                continue;
+            const filePath = node_path_1.default.join(subdirPath, file);
+            const content = await promises_1.default.readFile(filePath, "utf8").catch(() => "");
+            const tags = parseTags(content);
+            pages.push({
+                filePath,
+                pageId: file.replace(/\.md$/, ""),
+                category: subdir,
+                tags,
+                isUserSaved: tags.includes("query_result"),
+            });
+        }
+    }
+    return pages;
+}
+// ─── Recursive copy ────────────────────────────────────────────────────────────
+async function copyDir(src, dest) {
+    await promises_1.default.mkdir(dest, { recursive: true });
+    const entries = await promises_1.default.readdir(src, { withFileTypes: true });
+    for (const entry of entries) {
+        const srcPath = node_path_1.default.join(src, entry.name);
+        const destPath = node_path_1.default.join(dest, entry.name);
+        if (entry.isDirectory()) {
+            await copyDir(srcPath, destPath);
+        }
+        else {
+            await promises_1.default.copyFile(srcPath, destPath);
+        }
+    }
+}
+// ─── Count pages by category ───────────────────────────────────────────────────
+function countByCategory(pages) {
+    const counts = {};
+    for (const p of pages) {
+        counts[p.category] = (counts[p.category] ?? 0) + 1;
+    }
+    return counts;
+}
+async function run(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");
+    const wikiDir = node_path_1.default.join(docuDir, "wiki");
+    const dryRun = options.dryRun ?? false;
+    const quiet = options.quiet ?? false;
+    function info(msg) { if (!quiet)
+        console.log(msg); }
+    // ── Step 1: Pre-flight ──────────────────────────────────────────────────────
+    info(c.bold(`\n  🔄 DocuFlow Rewiki${dryRun ? c.yellow(" (dry-run)") : ""}\n`));
+    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 (!node_fs_1.default.existsSync(sourcesDir)) {
+        console.error(c.red(`  ✗ .docuflow/sources/ not found`));
+        console.error(`    Nothing to re-ingest.`);
+        process.exit(2);
+    }
+    // Count sources
+    const sourceFiles = (await promises_1.default.readdir(sourcesDir).catch(() => []))
+        .filter(f => f.endsWith(".md"));
+    info(`  📚 Sources: ${sourceFiles.length} file(s)`);
+    // Scan current wiki
+    const pagesBefore = await scanWiki(wikiDir);
+    const countsBefore = countByCategory(pagesBefore);
+    info(`  📖 Wiki pages before:`);
+    for (const [cat, n] of Object.entries(countsBefore)) {
+        info(`     ${cat}: ${n}`);
+    }
+    if (pagesBefore.length === 0) {
+        info(c.yellow(`     (none)`));
+    }
+    const userSavedPages = pagesBefore.filter(p => p.isUserSaved);
+    info(`  👤 User-saved synthesis pages: ${userSavedPages.length} (will be preserved)`);
+    if (dryRun) {
+        info(c.yellow(`\n  ℹ️  Dry-run mode — no files will be written.\n`));
+    }
+    // ── Step 2: Backup ──────────────────────────────────────────────────────────
+    let backupPath = "skipped";
+    if (!options.noBackup && !dryRun) {
+        const isoStamp = new Date().toISOString().replace(/[:.]/g, "-");
+        backupPath = node_path_1.default.join(docuDir, `wiki.backup-${isoStamp}`);
+        info(`\n  💾 Backing up wiki → ${c.cyan(node_path_1.default.relative(projectPath, backupPath))}`);
+        if (node_fs_1.default.existsSync(wikiDir)) {
+            await copyDir(wikiDir, backupPath);
+            info(c.green(`  ✅ Backup complete`));
+        }
+        else {
+            info(c.yellow(`  ⚠  wiki/ does not exist — skipping backup`));
+            backupPath = "skipped (wiki/ missing)";
+        }
+    }
+    else if (options.noBackup) {
+        info(`\n  ⚠  Backup skipped (--no-backup)`);
+    }
+    // ── Step 3: Migrate synthesiss/ typo (defense-in-depth) ────────────────────
+    const synthesissDir = node_path_1.default.join(wikiDir, "synthesiss");
+    const synthesesDir = node_path_1.default.join(wikiDir, "syntheses");
+    const migratedFiles = [];
+    if (!dryRun && node_fs_1.default.existsSync(synthesissDir)) {
+        info(`\n  🔧 Migrating synthesiss/ → syntheses/ (typo fix)`);
+        await promises_1.default.mkdir(synthesesDir, { recursive: true });
+        const files = await promises_1.default.readdir(synthesissDir).catch(() => []);
+        for (const f of files) {
+            const src = node_path_1.default.join(synthesissDir, f);
+            const dest = node_path_1.default.join(synthesesDir, f);
+            await promises_1.default.rename(src, dest);
+            migratedFiles.push(f);
+            info(c.dim(`     → ${f}`));
+        }
+        await promises_1.default.rmdir(synthesissDir).catch(() => { });
+        info(c.green(`  ✅ Migrated ${migratedFiles.length} file(s), removed synthesiss/`));
+    }
+    else if (dryRun && node_fs_1.default.existsSync(synthesissDir)) {
+        const files = await promises_1.default.readdir(synthesissDir).catch(() => []);
+        info(`\n  🔧 [dry-run] Would migrate ${files.length} file(s) from synthesiss/ → syntheses/`);
+        migratedFiles.push(...files);
+    }
+    // ── Step 4: Clear auto-generated pages & re-ingest ─────────────────────────
+    const pagesAfterIds = new Set();
+    let ingestErrors = 0;
+    const rejectedPages = [];
+    if (!dryRun) {
+        // Delete auto-generated pages (not user-saved) before re-ingesting
+        // so old noise pages are removed even if no new equivalent is created
+        info(`\n  🗑  Clearing auto-generated wiki pages...`);
+        let cleared = 0;
+        for (const page of pagesBefore) {
+            if (!page.isUserSaved) {
+                await promises_1.default.unlink(page.filePath).catch(() => { });
+                cleared++;
+            }
+        }
+        info(`     Cleared ${cleared} auto-generated page(s) (${userSavedPages.length} user-saved preserved)`);
+        // Load server tools
+        let ingestSource;
+        let updateIndex;
+        try {
+            ({ ingestSource } = loadServerTool("ingest-source"));
+            ({ updateIndex } = loadServerTool("update-index"));
+        }
+        catch (e) {
+            console.error(c.red(`  ✗ ${e.message}`));
+            process.exit(2);
+        }
+        // Re-ingest all sources
+        info(`\n  📥 Re-ingesting ${sourceFiles.length} source file(s)...`);
+        for (const filename of sourceFiles) {
+            try {
+                const result = await ingestSource({ project_path: projectPath, source_filename: filename });
+                const created = result.pages_created ?? [];
+                for (const id of created)
+                    pagesAfterIds.add(id);
+                info(`     ${c.green("✓")} ${filename} → ${created.length} page(s)`);
+            }
+            catch (e) {
+                info(c.red(`     ✗ ${filename}: ${e.message}`));
+                ingestErrors++;
+            }
+        }
+        // ── Step 5: Update index ────────────────────────────────────────────────
+        info(`\n  📋 Rebuilding index...`);
+        const indexResult = await updateIndex({ project_path: projectPath });
+        info(c.green(`  ✅ Index rebuilt — ${indexResult.entries_indexed ?? "?"} entries`));
+    }
+    else {
+        // Dry-run: simulate what would happen
+        info(`\n  📥 [dry-run] Would re-ingest ${sourceFiles.length} source file(s)`);
+        let { ingestSource } = (() => {
+            try {
+                return loadServerTool("ingest-source");
+            }
+            catch {
+                return { ingestSource: null };
+            }
+        })();
+        if (ingestSource) {
+            for (const filename of sourceFiles) {
+                try {
+                    const result = await ingestSource({ project_path: projectPath, source_filename: filename });
+                    for (const id of (result.pages_created ?? []))
+                        pagesAfterIds.add(id);
+                    info(`     ${c.dim("~")} ${filename} → ${(result.pages_created ?? []).length} page(s) (dry-run)`);
+                }
+                catch { }
+            }
+        }
+    }
+    // ── Pages removed = before - after - user-saved ───────────────────────────
+    for (const page of pagesBefore) {
+        if (!page.isUserSaved && !pagesAfterIds.has(page.pageId)) {
+            rejectedPages.push({ pageId: page.pageId, category: page.category });
+        }
+    }
+    // ── Step 6: Write report ────────────────────────────────────────────────────
+    const reportPath = node_path_1.default.join(docuDir, "rewiki-report.md");
+    const pagesAfter = dryRun ? pagesBefore : await scanWiki(wikiDir);
+    const countsAfter = countByCategory(pagesAfter);
+    const now = new Date().toISOString();
+    const reportLines = [
+        `# DocuFlow Rewiki Report`,
+        ``,
+        `**Timestamp:** ${now}`,
+        `**Dry-run:** ${dryRun}`,
+        `**Backup path:** ${backupPath}`,
+        ``,
+        `## Pages Before`,
+        ``,
+        ...Object.entries(countsBefore).map(([cat, n]) => `- ${cat}: ${n}`),
+        `- **Total:** ${pagesBefore.length}`,
+        ``,
+        `## Pages After`,
+        ``,
+        ...Object.entries(countsAfter).map(([cat, n]) => `- ${cat}: ${n}`),
+        `- **Total:** ${pagesAfter.length}`,
+        ``,
+        `## Removed Pages (${rejectedPages.length})`,
+        ``,
+        rejectedPages.length > 0
+            ? rejectedPages.map(p => `- \`${p.pageId}\` (${p.category})`).join("\n")
+            : "None.",
+        ``,
+        `## Preserved User-Saved Pages (${userSavedPages.length})`,
+        ``,
+        userSavedPages.length > 0
+            ? userSavedPages.map(p => `- \`${p.pageId}\``).join("\n")
+            : "None.",
+        ``,
+    ];
+    if (migratedFiles.length > 0) {
+        reportLines.push(`## synthesiss/ Migrations (${migratedFiles.length})`, ``, ...migratedFiles.map(f => `- ${f}`), ``);
+    }
+    const reportContent = reportLines.join("\n");
+    if (!dryRun) {
+        await promises_1.default.writeFile(reportPath, reportContent, "utf8");
+        info(`\n  📄 Report written → ${c.cyan(node_path_1.default.relative(projectPath, reportPath))}`);
+        // ── Step 7: Append to log.md ──────────────────────────────────────────────
+        const logPath = node_path_1.default.join(docuDir, "log.md");
+        const logEntry = `\n## [${now.split("T")[0]}] rewiki | removed ${rejectedPages.length}, kept ${pagesAfter.length - userSavedPages.length}, preserved ${userSavedPages.length} user pages\n`;
+        try {
+            await promises_1.default.appendFile(logPath, logEntry, "utf8");
+        }
+        catch { }
+    }
+    else {
+        info(`\n  📄 [dry-run] Report would be written to ${c.cyan(node_path_1.default.relative(projectPath, reportPath))}`);
+    }
+    // ── Summary ─────────────────────────────────────────────────────────────────
+    info(`\n  ─────────────────────────────────────────────`);
+    info(`  Sources re-ingested:  ${dryRun ? "(dry-run)" : sourceFiles.length}`);
+    info(`  Pages before:         ${pagesBefore.length}`);
+    info(`  Pages after:          ${dryRun ? "(dry-run)" : pagesAfter.length}`);
+    info(`  Removed:              ${rejectedPages.length}`);
+    info(`  Preserved (user):     ${userSavedPages.length}`);
+    if (migratedFiles.length > 0) {
+        info(`  synthesiss/ migrated: ${migratedFiles.length}`);
+    }
+    if (ingestErrors > 0) {
+        info(`  Ingest errors:        ${c.red(String(ingestErrors))}`);
+    }
+    info(`  ─────────────────────────────────────────────\n`);
+    if (ingestErrors > 0)
+        process.exit(1);
+}

package/dist/index.js

@@ -45,157 +45,163 @@ function getFlagValue(flag) {
     const idx = rest.indexOf(flag);
     return idx !== -1 ? rest[idx + 1] : undefined;
 }
-if (cmd === '--version' || cmd === '-v') {
-    console.log(version);
+// ── hasFlagIn / getFlagValueIn — scoped to a specific args array ─────────────
+function hasFlagIn(arr, ...flags) {
+    return flags.some(f => arr.includes(f));
 }
-else if (cmd === 'init') {
-    if (hasFlag('--interactive', '-i')) {
-        Promise.resolve().then(() => __importStar(require('./commands/init-interactive'))).then(m => m.runInteractive());
+function getFlagValueIn(arr, flag) {
+    const idx = arr.indexOf(flag);
+    return idx !== -1 ? arr[idx + 1] : undefined;
+}
+// ── dispatch — routes a (cmd, cmdRest) pair to the right handler ──────────────
+function dispatch(c, r) {
+    if (c === '--version' || c === '-v') {
+        console.log(version);
+        // ── CORE ──────────────────────────────────────────────────────────────────
     }
-    else {
-        Promise.resolve().then(() => __importStar(require('./commands/init'))).then(m => m.run());
+    else if (c === 'init') {
+        if (hasFlagIn(r, '--interactive', '-i')) {
+            Promise.resolve().then(() => __importStar(require('./commands/init-interactive'))).then(m => m.runInteractive());
+        }
+        else {
+            Promise.resolve().then(() => __importStar(require('./commands/init'))).then(m => m.run());
+        }
     }
-}
-else if (cmd === 'status') {
-    Promise.resolve().then(() => __importStar(require('./commands/status'))).then(m => m.run());
-}
-else if (cmd === 'suggest') {
-    Promise.resolve().then(() => __importStar(require('./commands/suggest'))).then(m => m.run());
-    // ── ui / start — web interface ───────────────────────────────────────────────
-}
-else if (cmd === 'ui' || cmd === 'start') {
-    const portFlag = getFlagValue('--port');
-    Promise.resolve().then(() => __importStar(require('./commands/ui'))).then(m => m.run({
-        port: portFlag ? parseInt(portFlag, 10) : undefined,
-        noOpen: hasFlag('--no-open'),
-    }));
-    // ── watch — auto-sync daemon ─────────────────────────────────────────────────
-}
-else if (cmd === 'watch') {
-    const subCmd = rest[0];
-    if (subCmd === 'stop') {
-        Promise.resolve().then(() => __importStar(require('./commands/watch-stop'))).then(m => m.runStop(process.cwd()));
+    else if (c === 'status') {
+        Promise.resolve().then(() => __importStar(require('./commands/status'))).then(m => m.run());
+        // ── query — ask the wiki ──────────────────────────────────────────────────
+    }
+    else if (c === 'query') {
+        const question = r[0] && !r[0].startsWith('--') ? r[0] : '';
+        const maxSourcesFlag = getFlagValueIn(r, '--max-sources');
+        Promise.resolve().then(() => __importStar(require('./commands/query'))).then(m => m.run({
+            question,
+            maxSources: maxSourcesFlag ? parseInt(maxSourcesFlag, 10) : 5,
+            json: hasFlagIn(r, '--json'),
+            noCite: hasFlagIn(r, '--no-cite'),
+            saveAs: getFlagValueIn(r, '--save-as'),
+            quiet: hasFlagIn(r, '--quiet', '-q'),
+        }));
+        // ── ingest — ingest a source file into the wiki ───────────────────────────
     }
-    else if (subCmd === 'status') {
-        Promise.resolve().then(() => __importStar(require('./commands/watch-stop'))).then(m => m.runStatus(process.cwd()));
+    else if (c === 'ingest') {
+        const sourceFile = r[0] && !r[0].startsWith('--') ? r[0] : undefined;
+        Promise.resolve().then(() => __importStar(require('./commands/ingest'))).then(m => m.run({
+            sourceFile,
+            all: hasFlagIn(r, '--all'),
+            dryRun: hasFlagIn(r, '--dry-run'),
+            quiet: hasFlagIn(r, '--quiet', '-q'),
+        }));
+        // ── rewiki — re-ingest all sources with new extractor rules ──────────────
     }
-    else if (subCmd === 'restart') {
-        Promise.resolve().then(() => __importStar(require('./commands/watch-stop'))).then(m => m.runRestart(process.cwd()));
+    else if (c === 'rewiki') {
+        Promise.resolve().then(() => __importStar(require('./commands/rewiki'))).then(m => m.run({
+            dryRun: hasFlagIn(r, '--dry-run'),
+            noBackup: hasFlagIn(r, '--no-backup'),
+            quiet: hasFlagIn(r, '--quiet', '-q'),
+        }));
+        // ── ADVANCED ──────────────────────────────────────────────────────────────
     }
-    else {
-        const lintHours = getFlagValue('--lint-interval');
-        const codeExt = getFlagValue('--code-ext');
-        Promise.resolve().then(() => __importStar(require('./commands/watch'))).then(m => m.run({
-            ai: hasFlag('--ai'),
-            forceCopilot: hasFlag('--copilot'),
-            forceClaude: hasFlag('--claude'),
-            forceCodex: hasFlag('--codex'),
-            lintIntervalHours: lintHours ? Number(lintHours) : 24,
-            codeExtensions: codeExt ? codeExt.split(',') : undefined,
-            allowDangerousPermissions: hasFlag('--allow-dangerous-permissions'),
+    else if (c === 'suggest') {
+        Promise.resolve().then(() => __importStar(require('./commands/suggest'))).then(m => m.run());
+        // ── ui / start — web interface ────────────────────────────────────────────
+    }
+    else if (c === 'ui' || c === 'start') {
+        const portFlag = getFlagValueIn(r, '--port');
+        Promise.resolve().then(() => __importStar(require('./commands/ui'))).then(m => m.run({
+            port: portFlag ? parseInt(portFlag, 10) : undefined,
+            noOpen: hasFlagIn(r, '--no-open'),
         }));
+        // ── watch — auto-sync daemon ──────────────────────────────────────────────
+    }
+    else if (c === 'watch') {
+        const subCmd = r[0];
+        if (subCmd === 'stop') {
+            Promise.resolve().then(() => __importStar(require('./commands/watch-stop'))).then(m => m.runStop(process.cwd()));
+        }
+        else if (subCmd === 'status') {
+            Promise.resolve().then(() => __importStar(require('./commands/watch-stop'))).then(m => m.runStatus(process.cwd()));
+        }
+        else if (subCmd === 'restart') {
+            Promise.resolve().then(() => __importStar(require('./commands/watch-stop'))).then(m => m.runRestart(process.cwd()));
+        }
+        else {
+            const lintHours = getFlagValueIn(r, '--lint-interval');
+            const codeExt = getFlagValueIn(r, '--code-ext');
+            Promise.resolve().then(() => __importStar(require('./commands/watch'))).then(m => m.run({
+                ai: hasFlagIn(r, '--ai'),
+                forceCopilot: hasFlagIn(r, '--copilot'),
+                forceClaude: hasFlagIn(r, '--claude'),
+                forceCodex: hasFlagIn(r, '--codex'),
+                lintIntervalHours: lintHours ? Number(lintHours) : 24,
+                codeExtensions: codeExt ? codeExt.split(',') : undefined,
+                allowDangerousPermissions: hasFlagIn(r, '--allow-dangerous-permissions'),
+            }));
+        }
+        // ── sync — one-shot sync for CI/CD and git hooks ──────────────────────────
+    }
+    else if (c === 'sync') {
+        const sinceCommit = getFlagValueIn(r, '--since-commit');
+        const sourceFile = getFlagValueIn(r, '--source');
+        const failScore = getFlagValueIn(r, '--fail-on-score');
+        Promise.resolve().then(() => __importStar(require('./commands/sync'))).then(m => m.run({
+            ai: hasFlagIn(r, '--ai'),
+            forceCopilot: hasFlagIn(r, '--copilot'),
+            forceClaude: hasFlagIn(r, '--claude'),
+            forceCodex: hasFlagIn(r, '--codex'),
+            sinceCommit,
+            sourceFile,
+            noLint: hasFlagIn(r, '--no-lint'),
+            failOnScore: failScore ? Number(failScore) : 70,
+            quiet: hasFlagIn(r, '--quiet', '-q'),
+            allowDangerousPermissions: hasFlagIn(r, '--allow-dangerous-permissions'),
+        }));
+        // ── review — git change review & improvement suggestions ──────────────────
+    }
+    else if (c === 'review') {
+        Promise.resolve().then(() => __importStar(require('./commands/review'))).then(m => m.run({
+            staged: hasFlagIn(r, '--staged'),
+            sinceCommit: getFlagValueIn(r, '--since-commit'),
+            ai: hasFlagIn(r, '--ai'),
+            failOnCritical: hasFlagIn(r, '--fail-on-critical'),
+            quiet: hasFlagIn(r, '--quiet', '-q'),
+        }));
+        // ── update — reinstall latest @doquflow/cli globally ─────────────────────
+    }
+    else if (c === 'update' || c === 'upgrade') {
+        Promise.resolve().then(() => __importStar(require('./commands/update'))).then(m => m.run({
+            check: hasFlagIn(r, '--check'),
+            force: hasFlagIn(r, '--force'),
+        }));
+        // ── recent — show recent task activity ────────────────────────────────────
+    }
+    else if (c === 'recent') {
+        const daysFlag = getFlagValueIn(r, '--days');
+        const fmt = getFlagValueIn(r, '--format');
+        Promise.resolve().then(() => __importStar(require('./commands/recent'))).then(m => m.run({
+            days: daysFlag ? (isNaN(parseInt(daysFlag, 10)) ? 7 : parseInt(daysFlag, 10)) : 7,
+            format: fmt ?? 'table',
+        }));
+        // ── unknown command ───────────────────────────────────────────────────────
+    }
+    else {
+        Promise.resolve().then(() => __importStar(require('./commands/help'))).then(m => m.printCoreHelp());
     }
-    // ── sync — one-shot sync for CI/CD and git hooks ─────────────────────────────
-}
-else if (cmd === 'sync') {
-    const sinceCommit = getFlagValue('--since-commit');
-    const sourceFile = getFlagValue('--source');
-    const failScore = getFlagValue('--fail-on-score');
-    Promise.resolve().then(() => __importStar(require('./commands/sync'))).then(m => m.run({
-        ai: hasFlag('--ai'),
-        forceCopilot: hasFlag('--copilot'),
-        forceClaude: hasFlag('--claude'),
-        forceCodex: hasFlag('--codex'),
-        sinceCommit,
-        sourceFile,
-        noLint: hasFlag('--no-lint'),
-        failOnScore: failScore ? Number(failScore) : 70,
-        quiet: hasFlag('--quiet', '-q'),
-        allowDangerousPermissions: hasFlag('--allow-dangerous-permissions'),
-    }));
-    // ── review — git change review & improvement suggestions ───────────────────────
-}
-else if (cmd === 'review') {
-    Promise.resolve().then(() => __importStar(require('./commands/review'))).then(m => m.run({
-        staged: hasFlag('--staged'),
-        sinceCommit: getFlagValue('--since-commit'),
-        ai: hasFlag('--ai'),
-        failOnCritical: hasFlag('--fail-on-critical'),
-        quiet: hasFlag('--quiet', '-q'),
-    }));
-    // ── update — reinstall latest @doquflow/cli globally ─────────────────────────
 }
-else if (cmd === 'update' || cmd === 'upgrade') {
-    Promise.resolve().then(() => __importStar(require('./commands/update'))).then(m => m.run({
-        check: hasFlag('--check'),
-        force: hasFlag('--force'),
-    }));
-    // ── recent — show recent DevLoop task activity ────────────────────────────────
+// ── Entry point ───────────────────────────────────────────────────────────────
+if (!cmd || cmd === '--help' || cmd === '-h') {
+    Promise.resolve().then(() => __importStar(require('./commands/help'))).then(m => m.printCoreHelp());
+    // ── advanced — optional prefix for the advanced surface ──────────────────────
 }
-else if (cmd === 'recent') {
-    const daysFlag = getFlagValue('--days');
-    const fmt = getFlagValue('--format');
-    Promise.resolve().then(() => __importStar(require('./commands/recent'))).then(m => m.run({
-        days: daysFlag ? (isNaN(parseInt(daysFlag, 10)) ? 7 : parseInt(daysFlag, 10)) : 7,
-        format: fmt ?? 'table',
-    }));
+else if (cmd === 'advanced') {
+    const [advCmd, ...advRest] = rest;
+    if (!advCmd || advCmd === '--help' || advCmd === '-h') {
+        Promise.resolve().then(() => __importStar(require('./commands/help'))).then(m => m.printAdvancedHelp());
+    }
+    else {
+        dispatch(advCmd, advRest);
+    }
 }
 else {
-    console.log(`DocuFlow v${version}`);
-    console.log('');
-    console.log('Usage: docuflow <command> [options]');
-    console.log('');
-    console.log('Commands:');
-    console.log('  init                    Register DocuFlow MCP and generate CLAUDE.md');
-    console.log('  init --interactive      Interactive setup wizard');
-    console.log('  status                  Show wiki health, page counts, and MCP status');
-    console.log('  suggest                 Show what to document first (domain-specific)');
-    console.log('  ui                      Start the DocuFlow web interface (API + UI on port 48821)');
-    console.log('  start                   Alias for "ui" — same web interface');
-    console.log('  ui --port <n>           Use a custom port (default: 48821)');
-    console.log('  ui --no-open            Start server without auto-opening the browser');
-    console.log('  watch                   Start auto-sync daemon (watches for changes)');
-    console.log('  watch --ai              Auto-detect best AI bridge (copilot > claude > codex > api)');
-    console.log('  watch --ai --copilot    Force @github/copilot CLI (direct MCP tool calling ⚡)');
-    console.log('  watch --ai --claude     Force Claude Code CLI    (direct MCP tool calling ⚡)');
-    console.log('  watch --ai --codex      Force Codex CLI          (generates doc → ingest)');
-    console.log('  watch --lint-interval N Run lint every N hours (default: 24)');
-    console.log('  watch --code-ext ts,py  Watch only these file extensions');
-    console.log('  watch stop              Stop the running watch daemon for this project');
-    console.log('  watch status            Show daemon state: running/stopped, PID, uptime, bridge');
-    console.log('  watch restart           Stop current daemon and restart with same options');
-    console.log('  sync                    One-shot sync: ingest all sources + rebuild index');
-    console.log('  sync --ai               AI-powered sync (auto-detects bridge)');
-    console.log('  sync --ai --copilot     Copilot drives DocuFlow MCP tools directly ⚡');
-    console.log('  sync --ai --claude      Claude drives DocuFlow MCP tools directly ⚡');
-    console.log('  sync --ai --codex       Codex generates doc → ingest');
-    console.log('  sync --since-commit REF Diff code changes since git ref (e.g. HEAD~1)');
-    console.log('  sync --source FILE      Sync a single source file');
-    console.log('  sync --no-lint          Skip health check (faster)');
-    console.log('  sync --fail-on-score N  Exit 1 if health score < N (default: 70)');
-    console.log('  sync --quiet            Suppress output (CI mode)');
-    console.log('  review                  Review current git changes and suggest improvements');
-    console.log('  review --staged         Review staged changes only');
-    console.log('  review --since-commit REF Review changes since git ref (e.g. HEAD~1)');
-    console.log('  review --ai             Append Copilot AI review to deterministic findings');
-    console.log('  review --fail-on-critical Exit 1 if critical findings are detected');
-    console.log('  review --quiet          Compact output for CI/scripting');
-    console.log('  update                  Reinstall latest @doquflow/cli globally (refreshes UI + server)');
-    console.log('  update --check          Check whether a newer version is published (no install)');
-    console.log('  update --force          Reinstall even when already on the latest version');
-    console.log('  upgrade                 Alias for "update"');
-    console.log('  recent [--days N] [--format table|md]   Show recent DevLoop task activity');
-    console.log('');
-    console.log('Options:');
-    console.log('  --version, -v                    Print version number');
-    console.log('  --allow-dangerous-permissions    Pass --dangerously-skip-permissions to Claude CLI');
-    console.log('                                   Required for Claude bridge in non-interactive use.');
-    console.log('                                   Only use when file content in this project is trusted.');
-    console.log('');
-    console.log('AI bridge priority (for --ai flag):');
-    console.log('  1. copilot  (@github/copilot) — calls DocuFlow MCP tools directly ⚡');
-    console.log('  2. claude   (Claude Code CLI) — calls DocuFlow MCP tools directly ⚡');
-    console.log('  3. codex    (OpenAI Codex CLI) — generates doc text, then ingests');
-    console.log('  4. api      (ANTHROPIC_API_KEY env) — generates doc text, then ingests');
-    console.log('  Use --copilot / --claude / --codex to override auto-detection.');
+    dispatch(cmd, rest);
 }