devsmind-mcp 2.2.0 → 2.3.0

package/dist/cli/workflow.js

@@ -0,0 +1,156 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.handleWorkflow = handleWorkflow;
+exports.handleWorkflowImport = handleWorkflowImport;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const prompts_1 = __importDefault(require("prompts"));
+const config_1 = require("../utils/config");
+const database_1 = require("../db/database");
+const workflow_import_1 = require("../db/workflow-import");
+function openDb(pathOpt) {
+    const devmindDir = (0, config_1.resolveDevmindDir)(pathOpt);
+    if (!devmindDir) {
+        console.error(`❌ No .devmind directory found.\n` +
+            `   Run from inside a DevsMind brain folder, or pass --path <devmind_path>.`);
+        process.exit(1);
+    }
+    return { db: new database_1.DevMindDatabase(path.join(devmindDir, 'brain.db')), devmindDir };
+}
+/** `devsmind workflow` — interactive list/view/pause/resume. Day-to-day creation and step-recording happens through the MCP tools the agent calls, not this command. */
+async function handleWorkflow(opts) {
+    const { db } = openDb(opts.path);
+    try {
+        await runWorkflowLoop(db);
+    }
+    finally {
+        db.close();
+    }
+}
+async function runWorkflowLoop(db) {
+    while (true) {
+        const workflows = db.listWorkflows();
+        if (workflows.length === 0) {
+            console.log('📝 No workflows yet. Create one via the workflow_create MCP tool, or import existing docs with `devsmind workflow import <path>`.');
+            return;
+        }
+        const statusEmoji = { active: '🟢', paused: '⏸️', completed: '✅' };
+        const choices = workflows.map(w => ({
+            title: `${statusEmoji[w.status] || ''} [${w.status}] ${w.name}`,
+            value: w.id
+        }));
+        choices.push({ title: '🚪 Exit', value: 'exit' });
+        const response = await (0, prompts_1.default)({
+            type: 'select',
+            name: 'id',
+            message: `Workflows (${workflows.length}):`,
+            choices
+        });
+        if (!response.id || response.id === 'exit') {
+            console.log('🚪 Goodbye!');
+            break;
+        }
+        await showWorkflowMenu(db, response.id);
+    }
+}
+async function showWorkflowMenu(db, id) {
+    while (true) {
+        let workflow;
+        let steps, artifacts;
+        try {
+            ({ workflow, steps, artifacts } = db.getWorkflowContext(id));
+        }
+        catch {
+            return;
+        }
+        console.log(`\n==================================================`);
+        console.log(`📋 ${workflow.name}  [${workflow.status}]`);
+        console.log(`==================================================`);
+        console.log(workflow.description);
+        console.log(`\nSteps (${steps.length}):`);
+        for (const s of steps) {
+            console.log(`  ${s.step_index}. ${s.summary}${s.pending_tasks ? `  (pending: ${s.pending_tasks})` : ''}`);
+        }
+        console.log(`\nArtifacts (${artifacts.length}):`);
+        for (const a of artifacts) {
+            console.log(`  - [${a.type}] ${a.source_name} → ${a.file_path.replace(/\\/g, '/')}`);
+        }
+        const choices = [];
+        if (workflow.status !== 'active')
+            choices.push({ title: '▶️ Resume (make active)', value: 'resume' });
+        if (workflow.status === 'active')
+            choices.push({ title: '⏸️ Pause', value: 'pause' });
+        if (workflow.status !== 'completed')
+            choices.push({ title: '✅ Mark completed', value: 'complete' });
+        choices.push({ title: '⬅️ Back to list', value: 'back' });
+        const response = await (0, prompts_1.default)({ type: 'select', name: 'action', message: 'Action:', choices });
+        if (!response.action || response.action === 'back')
+            return;
+        if (response.action === 'resume')
+            db.resumeWorkflow(id);
+        if (response.action === 'pause')
+            db.pauseWorkflow();
+        if (response.action === 'complete')
+            db.completeWorkflow(id);
+    }
+}
+/** `devsmind workflow import <path>` — imports a folder of .md flow docs, or a single file, as paused workflows. */
+async function handleWorkflowImport(pathArg, opts) {
+    const { db } = openDb(opts.path);
+    try {
+        const resolved = path.resolve(pathArg);
+        const isDir = fs.existsSync(resolved) && fs.statSync(resolved).isDirectory();
+        const result = (0, workflow_import_1.importWorkflowDocs)(db, isDir ? resolved : undefined, isDir ? undefined : resolved);
+        console.log(`\n📥 Import complete.`);
+        if (result.created.length)
+            console.log(`   Created (${result.created.length}): ${result.created.join(', ')}`);
+        if (result.updated.length)
+            console.log(`   Updated (${result.updated.length}): ${result.updated.join(', ')}`);
+        if (result.skipped.length)
+            console.log(`   Skipped (${result.skipped.length}): ${result.skipped.join(', ')}`);
+        if (!result.created.length && !result.updated.length && !result.skipped.length) {
+            console.log('   Nothing to import.');
+        }
+        console.log();
+    }
+    finally {
+        db.close();
+    }
+}
+//# sourceMappingURL=workflow.js.map

package/dist/cli/workflow.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"workflow.js","sourceRoot":"","sources":["../../src/cli/workflow.ts"],"names":[],"mappings":"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"}

package/dist/db/analyze.d.ts

@@ -0,0 +1,67 @@
+import { DevMindDatabase } from './database';
+export interface AnalysisOptions {
+    fix?: boolean;
+    godEntityThreshold?: number;
+}
+export interface AnalysisReport {
+    fixed: boolean;
+    summary: Record<string, number>;
+    god_entities: {
+        id: string;
+        name: string;
+        file_path: string;
+        degree: number;
+    }[];
+    circular_dependencies: string[][];
+    orphaned_nodes: {
+        id: string;
+        name: string;
+        file_path: string;
+    }[];
+    dangling_edges: {
+        source_node_id: string;
+        target_node_id: string;
+    }[];
+    duplicate_ids: {
+        lower_id: string;
+        ids: string[];
+    }[];
+    missing_developer_attribution: {
+        id: string;
+        node_id: string;
+        updated_at: string;
+    }[];
+    empty_code_snapshots: {
+        id: string;
+        node_id: string;
+        updated_at: string;
+    }[];
+    spurious_nodes: {
+        id: string;
+        name: string;
+        file_path: string;
+    }[];
+    missing_files: {
+        id: string;
+        name: string;
+        file_path: string;
+    }[];
+    renamed_files: {
+        repo: string;
+        from: string;
+        to: string;
+        migrated: boolean;
+    }[];
+    untracked_files: {
+        repo: string;
+        file: string;
+    }[];
+}
+/**
+ * Runs every local, zero-AI health check against the graph and — when `fix` is true —
+ * applies only the safe/reversible fixes (soft-deprecate dead nodes, delete dangling
+ * edges, migrate renames). Everything else is report-only: god entities, cycles,
+ * duplicate ids, missing developer attribution, empty snapshots, and untracked files
+ * all need human/AI judgement a mechanical fixer shouldn't make on its own.
+ */
+export declare function runAnalysis(db: DevMindDatabase, workspaceRoot: string, opts?: AnalysisOptions): AnalysisReport;

package/dist/db/analyze.js

@@ -0,0 +1,163 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runAnalysis = runAnalysis;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const config_1 = require("../utils/config");
+const git_1 = require("../utils/git");
+const scanner_1 = require("../utils/scanner");
+const LAST_ANALYSIS_KEY = 'last_analysis_at';
+const DEFAULT_LOOKBACK_DAYS = 30;
+/**
+ * Runs every local, zero-AI health check against the graph and — when `fix` is true —
+ * applies only the safe/reversible fixes (soft-deprecate dead nodes, delete dangling
+ * edges, migrate renames). Everything else is report-only: god entities, cycles,
+ * duplicate ids, missing developer attribution, empty snapshots, and untracked files
+ * all need human/AI judgement a mechanical fixer shouldn't make on its own.
+ */
+function runAnalysis(db, workspaceRoot, opts = {}) {
+    const fix = opts.fix === true;
+    const godEntityThreshold = opts.godEntityThreshold ?? 15;
+    const god_entities = db.getGodEntities(godEntityThreshold);
+    const circular_dependencies = db.getCircularDependencies();
+    const orphaned_nodes = db.getOrphanedNodes().map(n => ({ id: n.id, name: n.name, file_path: n.file_path }));
+    const dangling_edges = db.getDanglingEdges().map(c => ({ source_node_id: c.source_node_id, target_node_id: c.target_node_id }));
+    const duplicate_ids = db.getDuplicateNodeIds().map(d => ({ lower_id: d.lowerId, ids: d.ids }));
+    const missing_developer_attribution = db.getHistoryMissingDeveloper();
+    const empty_code_snapshots = db.getEmptyCodeSnapshots();
+    const { spurious: spurious_nodes, missingFile: missing_files } = db.findSpuriousAndMissingFileNodes(workspaceRoot);
+    const lastAnalysisAt = db.getSystemMeta(LAST_ANALYSIS_KEY);
+    const lookbackIso = lastAnalysisAt || new Date(Date.now() - DEFAULT_LOOKBACK_DAYS * 24 * 60 * 60 * 1000).toISOString();
+    const renamed_files = [];
+    const untracked_files = [];
+    const context = db.getContext();
+    if (context) {
+        for (const repo of context.config.repos) {
+            const repoPath = (0, config_1.resolveRepoPath)(context, repo.name);
+            if (!repoPath || !fs.existsSync(repoPath))
+                continue;
+            for (const r of (0, git_1.getRenamedFilesSince)(repoPath, lookbackIso)) {
+                renamed_files.push({ repo: repo.name, from: r.from, to: r.to, migrated: false });
+            }
+            const changed = (0, git_1.getChangedFilesSince)(repoPath, lookbackIso);
+            const knownFiles = new Set(db.listNodes({ include_deprecated: true }).flatMap(n => (n.file_path || '').split(',').map(p => p.trim()).filter(Boolean)));
+            for (const relFile of changed) {
+                const ext = path.extname(relFile).toLowerCase();
+                if (!scanner_1.INDEXABLE_EXTENSIONS.has(ext))
+                    continue;
+                const absFile = path.resolve(repoPath, relFile);
+                if (!fs.existsSync(absFile))
+                    continue; // deleted since — not a blind spot
+                const hasNode = Array.from(knownFiles).some(f => path.resolve(f) === absFile);
+                if (!hasNode)
+                    untracked_files.push({ repo: repo.name, file: relFile });
+            }
+        }
+    }
+    if (fix) {
+        for (const n of [...orphaned_nodes, ...spurious_nodes, ...missing_files]) {
+            db.deprecateNode(n.id);
+        }
+        for (const e of dangling_edges) {
+            db.deleteDanglingEdge(e.source_node_id, e.target_node_id);
+        }
+        if (context) {
+            for (const r of renamed_files) {
+                const migrated = migrateRename(db, context, r.repo, r.from, r.to);
+                r.migrated = migrated;
+            }
+        }
+        db.setSystemMeta(LAST_ANALYSIS_KEY, new Date().toISOString());
+    }
+    const summary = {
+        god_entities: god_entities.length,
+        circular_dependencies: circular_dependencies.length,
+        orphaned_nodes: orphaned_nodes.length,
+        dangling_edges: dangling_edges.length,
+        duplicate_ids: duplicate_ids.length,
+        missing_developer_attribution: missing_developer_attribution.length,
+        empty_code_snapshots: empty_code_snapshots.length,
+        spurious_nodes: spurious_nodes.length,
+        missing_files: missing_files.length,
+        renamed_files: renamed_files.length,
+        untracked_files: untracked_files.length,
+    };
+    return {
+        fixed: fix,
+        summary,
+        god_entities,
+        circular_dependencies,
+        orphaned_nodes,
+        dangling_edges,
+        duplicate_ids,
+        missing_developer_attribution,
+        empty_code_snapshots,
+        spurious_nodes,
+        missing_files,
+        renamed_files,
+        untracked_files,
+    };
+}
+/** Migrates every node whose file_path resolves to `from` onto `to`, cascading the id/connections/history via `renameNode`. Returns true if anything was migrated. */
+function migrateRename(db, context, repoName, from, to) {
+    if (!context)
+        return false;
+    const repoPath = (0, config_1.resolveRepoPath)(context, repoName);
+    if (!repoPath)
+        return false;
+    const oldAbs = path.resolve(repoPath, from);
+    const newAbs = path.resolve(repoPath, to);
+    // Deliberately excludes deprecated nodes — renameNode's insert doesn't preserve the
+    // deprecated flag, so migrating a dead node would silently resurrect it as active.
+    // A deprecated node's file_path accuracy doesn't matter once it's already excluded
+    // from use.
+    const affected = db.listNodes().filter(n => (n.file_path || '').split(',').map(p => p.trim()).some(p => path.resolve(p) === oldAbs));
+    let migrated = false;
+    for (const node of affected) {
+        const newId = node.id.replace(from, to);
+        if (newId === node.id)
+            continue;
+        try {
+            db.renameNode(node.id, newId, undefined, newAbs);
+            migrated = true;
+        }
+        catch {
+            // Leave this node untouched — analyze reports it again next run rather than failing the whole batch.
+        }
+    }
+    return migrated;
+}
+//# sourceMappingURL=analyze.js.map

package/dist/db/analyze.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"analyze.js","sourceRoot":"","sources":["../../src/db/analyze.ts"],"names":[],"mappings":"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"}

package/dist/db/database.d.ts

@@ -1,4 +1,5 @@
-import { DbNode, DbHistory, DbConnection } from './schema';
+import { DbNode, DbHistory, DbConnection, DbWorkflow, DbWorkflowStep, DbWorkflowArtifact } from './schema';
+import { ProjectContext } from '../utils/config';
 export interface ReasoningObject {
     what_changed: string;
     why: string;
@@ -48,6 +49,7 @@ export declare class DevMindDatabase {
     private context;
     constructor(dbPath: string);
     private initSchema;
+    getContext(): ProjectContext | null;
     getSystemMeta(key: string): string | null;
     setSystemMeta(key: string, value: string): void;
     getNodesByFilePath(filePath: string): DbNode[];
@@ -88,7 +90,8 @@ export declare class DevMindDatabase {
     getNode(id: string): DbNode | null;
     deleteNode(id: string): void;
     deprecateNode(id: string): void;
-    renameNode(oldId: string, newId: string, newName?: string): void;
+    /** `newFilePath`: pass when the rename is a file move (analyze's rename migration), leave undefined for a pure symbol-id rename where the file itself is unchanged. */
+    renameNode(oldId: string, newId: string, newName?: string, newFilePath?: string): void;
     /**
      * Rewrites a history/[id].json file's identifying fields (node_id, node_metadata) in
      * place, leaving code_snapshot/reasoning/timestamps untouched. Used after a rename so
@@ -153,7 +156,21 @@ export declare class DevMindDatabase {
         reasoning: string | ReasoningObject;
         session_id?: string;
     }): DbHistory;
-    searchNodes(query: string): DbNode[];
+    /**
+     * Search for nodes by name/id/reasoning first (cheap, SQL-only). If that finds
+     * nothing, transparently fall back to a code-content search (same engine as
+     * {@link searchCode}) so a query like "alipay" still succeeds even when no
+     * node's name/id/reasoning mentions it but the code itself does. Every result
+     * is tagged `matched_via` so the caller knows which path found it.
+     */
+    searchNodes(query: string, opts?: {
+        is_regex?: boolean;
+        case_insensitive?: boolean;
+    }): Array<(DbNode & {
+        matched_via: 'identifier';
+    }) | (ReturnType<DevMindDatabase['searchCode']>[number] & {
+        matched_via: 'code';
+    })>;
     getRecentChanges(hours?: number, analyzeImpact?: boolean): {
         node_id: string;
         node_name: string;
@@ -210,6 +227,135 @@ export declare class DevMindDatabase {
     }): DbNode[];
     getAllConnections(): DbConnection[];
     getAllHistory(): DbHistory[];
+    /** Nodes whose total (in + out) connection degree meets/exceeds `threshold` — architectural bottleneck candidates. */
+    getGodEntities(threshold?: number): {
+        id: string;
+        name: string;
+        file_path: string;
+        degree: number;
+    }[];
+    /** DFS cycle detection over the connection graph, capped at `maxCycles` reported paths. */
+    getCircularDependencies(maxCycles?: number): string[][];
+    /** node_connections rows whose source or target no longer exists in `nodes` (broken by a non-transactional delete, or a sync race). */
+    getDanglingEdges(): DbConnection[];
+    /** Deletes a single dangling `node_connections` row. The edge itself is invalid data — no history/graph JSON to rewrite. */
+    deleteDanglingEdge(sourceId: string, targetId: string): void;
+    /** Node ids that differ only by case — a real collision risk on Windows's case-insensitive filesystem. */
+    getDuplicateNodeIds(): {
+        lowerId: string;
+        ids: string[];
+    }[];
+    /** History rows whose flattened `reasoning` text has no non-empty `Developer:` line — can't be attributed to anyone. */
+    getHistoryMissingDeveloper(): {
+        id: string;
+        node_id: string;
+        updated_at: string;
+    }[];
+    /**
+     * History rows with a blank code snapshot — usually a silent AST extraction failure.
+     * The `history.code_snapshot` DB column is always written as `''` (the real content
+     * lives only in the per-row JSON on disk, see `populateHistoryFromDisk`), so this
+     * must read through the populated rows rather than querying the column directly.
+     */
+    getEmptyCodeSnapshots(): {
+        id: string;
+        node_id: string;
+        updated_at: string;
+    }[];
+    private workflowsDir;
+    /** Serializes the workflow + its steps + artifact index to disk so teammates can sync it via git. */
+    private writeWorkflowToDisk;
+    createWorkflow(name: string, description: string): DbWorkflow;
+    getWorkflow(id: string): DbWorkflow | null;
+    getActiveWorkflow(): DbWorkflow | null;
+    listWorkflows(status?: 'active' | 'paused' | 'completed'): DbWorkflow[];
+    /** Pauses the currently active workflow (if any) and clears the active pointer. */
+    pauseWorkflow(): DbWorkflow | null;
+    /** Resumes `id`, auto-pausing whatever was previously active (only one workflow is active at a time). */
+    resumeWorkflow(id: string): DbWorkflow;
+    completeWorkflow(id: string): DbWorkflow;
+    addWorkflowStep(workflowId: string, opts: {
+        summary: string;
+        pendingTasks?: string;
+        historyIds?: string[];
+        sessionId?: string;
+    }): DbWorkflowStep;
+    /** Writes `content` to `.devmind/workflows/<workflowId>/<artifactId>_<sourceName>` and records the DB row. */
+    addWorkflowArtifact(workflowId: string, opts: {
+        stepId?: string;
+        type: string;
+        sourceName: string;
+        content: string;
+    }): DbWorkflowArtifact;
+    getWorkflowContext(id: string, opts?: {
+        includeArtifactContent?: boolean;
+    }): {
+        workflow: DbWorkflow;
+        steps: DbWorkflowStep[];
+        artifacts: (DbWorkflowArtifact & {
+            content?: string;
+        })[];
+    };
+    /**
+     * Returns steps for a workflow with optional pagination.
+     * Use `last_n` to get only the most recent N steps (tail), or `limit`/`offset` for
+     * arbitrary pagination. Without any option, all steps are returned.
+     */
+    getWorkflowSteps(workflowId: string, opts?: {
+        limit?: number;
+        offset?: number;
+        last_n?: number;
+    }): DbWorkflowStep[];
+    /**
+     * Reads a single workflow artifact's file content from disk.
+     * Accepts either an artifact_id or a source_name (first match used).
+     */
+    readWorkflowArtifact(workflowId: string, artifactId: string): {
+        artifact: DbWorkflowArtifact;
+        content: string;
+    };
+    /**
+     * Full-text keyword search across all workflows' step summaries, pending_tasks,
+     * and artifact source names. Optionally also searches artifact file content.
+     * Returns a list of matches grouped by workflow.
+     */
+    searchWorkflows(query: string, opts?: {
+        include_artifact_content?: boolean;
+        status?: 'active' | 'paused' | 'completed';
+    }): Array<{
+        workflow: DbWorkflow;
+        matched_steps: DbWorkflowStep[];
+        matched_artifacts: (DbWorkflowArtifact & {
+            content_snippet?: string;
+        })[];
+    }>;
+    /**
+     * Imports an existing flow/architecture doc as a paused workflow (not active — importing
+     * a doc isn't the same as declaring active work). Idempotent on `name`: re-importing the
+     * same doc overwrites its existing `imported_doc` artifact file in place instead of
+     * creating a duplicate workflow every time the source docs are re-imported.
+     */
+    importWorkflowDoc(name: string, description: string, content: string, sourceFileName: string): {
+        workflow: DbWorkflow;
+        created: boolean;
+    };
+    private static readonly SPURIOUS_NODE_NAMES;
+    /**
+     * Read-only detection shared by `pruneSpuriousNodes` (which acts on it) and `devsmind
+     * analyze`'s dry-run report (which just lists it). Never mutates the DB.
+     */
+    findSpuriousAndMissingFileNodes(workspaceRoot: string): {
+        spurious: {
+            id: string;
+            name: string;
+            file_path: string;
+        }[];
+        missingFile: {
+            id: string;
+            name: string;
+            file_path: string;
+        }[];
+    };
     pruneSpuriousNodes(workspaceRoot: string): {
         prunedCount: number;
         prunedNodes: string[];
@@ -217,9 +363,26 @@ export declare class DevMindDatabase {
     private populateHistoryFromDisk;
     private writeHistoryToDisk;
     toRepoRelativePath(absolutePath: string): string;
+    /**
+     * Rejects a resolved path that escapes its expected root (e.g. via a stored
+     * `{repo}/../../..` path traveling outside the repo) by clamping it back to
+     * the root itself. node_id/file_path values flow in from AI-supplied tool
+     * calls, so a resolve must never be trusted to stay inside root on its own.
+     */
+    private clampToRoot;
+    /**
+     * True if `absPath` sits inside a configured repo root or the workspace root itself.
+     * Used to reject `stage_change`/`update_history` file paths that would otherwise let a
+     * tool call read/write any file on disk (absolute path, or a `../` escape) instead of
+     * just repo source — nothing upstream of this validates that the AI-supplied path is
+     * actually inside the project.
+     */
+    isPathAllowed(absPath: string): boolean;
     toAbsolutePath(repoRelativePath: string): string;
     syncFromDisk(): void;
     /** Escape LIKE metacharacters so a path is matched literally (use with ESCAPE '\\'). */
     private likeEscape;
     writeGraphToDisk(filePath: string): void;
+    /** Force-syncs all database nodes and workflows to disk JSON files. */
+    syncToDisk(): void;
 }