@maadb/core 0.0.1 → 0.7.9

package/dist/engine/docid-safe.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"docid-safe.d.ts","sourceRoot":"","sources":["../../src/engine/docid-safe.ts"],"names":[],"mappings":"AAuCA,MAAM,WAAW,cAAc;IAC7B,MAAM,EACF,OAAO,GACP,UAAU,GACV,iBAAiB,GACjB,aAAa,GACb,eAAe,GACf,kBAAkB,GAClB,eAAe,CAAC;IACpB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,cAAc,GAAG,IAAI,CAkCnE;AAED,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAGnD;AAED,eAAO,MAAM,cAAc,MAAiB,CAAC"}

package/dist/engine/docid-safe.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"docid-safe.js","sourceRoot":"","sources":["../../src/engine/docid-safe.ts"],"names":[],"mappings":"AAAA,+EAA+E;AAC/E,iDAAiD;AACjD,EAAE;AACF,uEAAuE;AACvE,0EAA0E;AAC1E,yEAAyE;AACzE,2EAA2E;AAC3E,wDAAwD;AACxD,EAAE;AACF,oEAAoE;AACpE,0EAA0E;AAC1E,2EAA2E;AAC3E,gCAAgC;AAChC,EAAE;AACF,2EAA2E;AAC3E,sEAAsE;AACtE,mEAAmE;AACnE,yEAAyE;AACzE,2EAA2E;AAC3E,+EAA+E;AAE/E,MAAM,cAAc,GAAG,GAAG,CAAC;AAE3B,MAAM,cAAc,GAAG,8CAA8C,CAAC;AAEtE,6EAA6E;AAC7E,4EAA4E;AAC5E,2EAA2E;AAC3E,MAAM,gBAAgB,GAAG,IAAI,GAAG,CAAC;IAC/B,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK;IAC1B,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM;IAC9E,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM;CAC/E,CAAC,CAAC;AAEH,yEAAyE;AACzE,8EAA8E;AAC9E,4CAA4C;AAC5C,MAAM,eAAe,GAAG,QAAQ,CAAC;AAcjC,MAAM,UAAU,cAAc,CAAC,KAAa;IAC1C,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACpD,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,EAAE,kCAAkC,EAAE,CAAC;IAC1E,CAAC;IACD,IAAI,KAAK,CAAC,MAAM,GAAG,cAAc,EAAE,CAAC;QAClC,OAAO;YACL,MAAM,EAAE,UAAU;YAClB,OAAO,EAAE,+BAA+B,cAAc,aAAa;SACpE,CAAC;IACJ,CAAC;IACD,0EAA0E;IAC1E,6DAA6D;IAC7D,IAAI,eAAe,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC;QAChC,OAAO,EAAE,MAAM,EAAE,eAAe,EAAE,OAAO,EAAE,mCAAmC,EAAE,CAAC;IACnF,CAAC;IACD,IAAI,KAAK,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;QAC1B,OAAO,EAAE,MAAM,EAAE,aAAa,EAAE,OAAO,EAAE,8BAA8B,EAAE,CAAC;IAC5E,CAAC;IACD,IAAI,KAAK,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC;QACzB,OAAO,EAAE,MAAM,EAAE,iBAAiB,EAAE,OAAO,EAAE,6CAA6C,EAAE,CAAC;IAC/F,CAAC;IACD,IAAI,CAAC,cAAc,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC;QAChC,OAAO;YACL,MAAM,EAAE,eAAe;YACvB,OAAO,EAAE,oHAAoH;SAC9H,CAAC;IACJ,CAAC;IACD,IAAI,gBAAgB,CAAC,GAAG,CAAC,KAAK,CAAC,WAAW,EAAE,CAAC,EAAE,CAAC;QAC9C,OAAO;YACL,MAAM,EAAE,kBAAkB;YAC1B,OAAO,EAAE,UAAU,KAAK,wCAAwC;SACjE,CAAC;IACJ,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED,MAAM,UAAU,eAAe,CAAC,KAAa;IAC3C,MAAM,GAAG,GAAG,cAAc,CAAC,KAAK,CAAC,CAAC;IAClC,IAAI,GAAG;QAAE,MAAM,IAAI,KAAK,CAAC,iBAAiB,GAAG,CAAC,OAAO,EAAE,CAAC,CAAC;AAC3D,CAAC;AAED,MAAM,CAAC,MAAM,cAAc,GAAG,cAAc,CAAC"}

package/dist/engine/helpers.d.ts

@@ -0,0 +1,8 @@
+import type { DocumentRecord } from '../types.js';
+export declare function readFrontmatter(projectRoot: string, doc: DocumentRecord): Promise<Record<string, unknown>>;
+export declare function readFrontmatterSync(projectRoot: string, doc: DocumentRecord): Record<string, unknown> | null;
+export declare function readBlockContent(projectRoot: string, doc: DocumentRecord, startLine: number, endLine: number, isPreamble: boolean): Promise<string>;
+export declare function generateDocId(prefix: string, fields: Record<string, unknown>, existingIds?: string[]): string;
+export declare function computeNumericValue(value: unknown, fieldType: string): number | null;
+export declare function collectMarkdownFiles(dirPath: string): Promise<string[]>;
+//# sourceMappingURL=helpers.d.ts.map

package/dist/engine/helpers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"helpers.d.ts","sourceRoot":"","sources":["../../src/engine/helpers.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAElD,wBAAsB,eAAe,CAAC,WAAW,EAAE,MAAM,EAAE,GAAG,EAAE,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAKhH;AAED,wBAAgB,mBAAmB,CAAC,WAAW,EAAE,MAAM,EAAE,GAAG,EAAE,cAAc,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAS5G;AAED,wBAAsB,gBAAgB,CAAC,WAAW,EAAE,MAAM,EAAE,GAAG,EAAE,cAAc,EAAE,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,OAAO,GAAG,OAAO,CAAC,MAAM,CAAC,CAOzJ;AAED,wBAAgB,aAAa,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,WAAW,CAAC,EAAE,MAAM,EAAE,GAAG,MAAM,CA+B7G;AAED,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,OAAO,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAkBpF;AAED,wBAAsB,oBAAoB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAkB7E"}

package/dist/engine/helpers.js

@@ -0,0 +1,102 @@
+// ============================================================================
+// Engine Helpers — file reading, ID generation, utility functions
+// ============================================================================
+import { readFile } from 'node:fs/promises';
+import { readFileSync } from 'node:fs';
+import path from 'node:path';
+import { glob } from 'node:fs/promises';
+import { parseMatter } from '../parser/matter.js';
+export async function readFrontmatter(projectRoot, doc) {
+    const absPath = path.join(projectRoot, doc.filePath);
+    const raw = await readFile(absPath, 'utf-8');
+    const parsed = parseMatter(raw);
+    return parsed.data;
+}
+export function readFrontmatterSync(projectRoot, doc) {
+    try {
+        const absPath = path.join(projectRoot, doc.filePath);
+        const raw = readFileSync(absPath, 'utf-8');
+        const parsed = parseMatter(raw);
+        return parsed.data;
+    }
+    catch {
+        return null;
+    }
+}
+export async function readBlockContent(projectRoot, doc, startLine, endLine, isPreamble) {
+    const absPath = path.join(projectRoot, doc.filePath);
+    const raw = await readFile(absPath, 'utf-8');
+    const lines = raw.split('\n');
+    const contentStart = isPreamble ? startLine - 1 : startLine;
+    const contentEnd = endLine;
+    return lines.slice(contentStart, contentEnd).join('\n').trim();
+}
+export function generateDocId(prefix, fields, existingIds) {
+    const nameOrTitle = fields['name'] ?? fields['title'];
+    // Slug strategy: use name/title if available
+    if (typeof nameOrTitle === 'string') {
+        const slug = nameOrTitle
+            .toLowerCase()
+            .replace(/[^a-z0-9\s-]/g, '')
+            .replace(/\s+/g, '-')
+            .replace(/-+/g, '-')
+            .replace(/^-|-$/g, '')
+            .slice(0, 40);
+        if (slug.length > 0)
+            return `${prefix}-${slug}`;
+    }
+    // Sequence strategy: prefix-YYYY-NNN
+    const year = new Date().getFullYear();
+    const seqPrefix = `${prefix}-${year}-`;
+    let maxSeq = 0;
+    if (existingIds) {
+        for (const id of existingIds) {
+            if (id.startsWith(seqPrefix)) {
+                const seqStr = id.slice(seqPrefix.length);
+                const num = parseInt(seqStr, 10);
+                if (!isNaN(num) && num > maxSeq)
+                    maxSeq = num;
+            }
+        }
+    }
+    return `${seqPrefix}${String(maxSeq + 1).padStart(3, '0')}`;
+}
+export function computeNumericValue(value, fieldType) {
+    if (value === null || value === undefined)
+        return null;
+    if (fieldType === 'number') {
+        const num = typeof value === 'number' ? value : parseFloat(String(value));
+        return isFinite(num) ? num : null;
+    }
+    if (fieldType === 'amount') {
+        const match = /^([\d,.]+)/.exec(String(value));
+        if (match) {
+            const num = parseFloat(match[1].replace(/,/g, ''));
+            return isFinite(num) ? num : null;
+        }
+        return null;
+    }
+    return null;
+}
+export async function collectMarkdownFiles(dirPath) {
+    const files = [];
+    try {
+        for await (const entry of glob('**/*.md', { cwd: dirPath })) {
+            const basename = path.basename(entry);
+            if (basename.startsWith('_deleted_'))
+                continue;
+            files.push(path.join(dirPath, entry));
+        }
+    }
+    catch {
+        const { readdir } = await import('node:fs/promises');
+        const entries = await readdir(dirPath, { withFileTypes: true });
+        for (const entry of entries) {
+            if (entry.isFile() && entry.name.endsWith('.md') && !entry.name.startsWith('_deleted_')) {
+                files.push(path.join(dirPath, entry.name));
+            }
+        }
+    }
+    return files;
+}
+//# sourceMappingURL=helpers.js.map

package/dist/engine/helpers.js.map

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

package/dist/engine/index.d.ts

@@ -0,0 +1,209 @@
+import { type Result } from '../errors.js';
+import type { DocId, DocType, FilePath, Registry, SchemaDefinition, ExtractionResult } from '../types.js';
+import type { MaadBackend } from '../backend/index.js';
+import { GitLayer } from '../git/index.js';
+import * as maintenance from './maintenance.js';
+export type { IndexResult, CreateResult, GetResult, UpdateResult, DeleteResult, FindResult, SearchResult, RelatedResult, DescribeResult, SummaryResult, GetFullResult, SchemaInfoResult, ValidationReport, VerifyResult, } from './types.js';
+export interface HealthReport {
+    projectRoot: string;
+    initialized: boolean;
+    readOnly: boolean;
+    gitAvailable: boolean;
+    indexExists: boolean;
+    lastIndexedAt: string | null;
+    totalDocuments: number;
+    registeredTypes: number;
+    recoveryActions: string[];
+    emptyProject: boolean;
+    bootstrapHint: string | null;
+    writeQueueDepth: number;
+    lastWriteOp: {
+        op: string;
+        startedAt: string;
+        elapsedMs: number;
+    } | null;
+    lastWriteAt: string | null;
+    repoSizeBytes: number | null;
+    gitClean: boolean | null;
+    diskHeadroomMb: number | null;
+    commitFailuresTotal: number;
+    lastCommitFailureAt: string | null;
+    lastCommitFailureCode: string | null;
+    lastCommitFailureAction: 'create' | 'update' | 'delete' | null;
+    lastCommitFailureDocId: string | null;
+}
+export declare class MaadEngine {
+    private projectRoot;
+    private registry;
+    private schemaStore;
+    private backend;
+    private gitLayer;
+    private journal;
+    private commitFailures;
+    private pendingCommitIdentity;
+    private initialized;
+    private _readOnly;
+    private startupRecovery;
+    private writeLock;
+    private lastWriteOp;
+    private lastWriteAt;
+    private repoSizeCache;
+    private static readonly REPO_SIZE_CACHE_MS;
+    private lastGitCleanCache;
+    /**
+     * Acquire the per-engine write mutex, run `fn`, release. Records
+     * `lastWriteOp` / `lastWriteAt` for health reporting and logs slow writes.
+     *
+     * **Reentrant.** When the current async context already holds this
+     * engine's write scope (e.g. `withEngine`'s write branch acquired at the
+     * MCP boundary, and the handler then calls `engine.createDocument` which
+     * itself wraps in `runExclusive`), the inner call skips acquisition and
+     * runs `fn` directly. Prevents double-locking deadlocks on a
+     * non-reentrant FIFO mutex. Bookkeeping (lastWriteOp/lastWriteAt) fires
+     * once per outermost scope.
+     *
+     * As of 0.5.0 R4 the MCP entry point is the primary caller — every tool
+     * classified as `write` in `src/mcp/kinds.ts` wraps here at the request
+     * boundary. Direct non-MCP callers (CLI, tests, import scripts) continue
+     * to call engine mutation methods normally; those methods self-wrap in
+     * runExclusive so direct callers stay serialized.
+     */
+    runExclusive<T>(op: string, fn: () => Promise<T>): Promise<T>;
+    init(projectRoot: string, opts?: {
+        readOnly?: boolean;
+    }): Promise<Result<void>>;
+    isReadOnly(): boolean;
+    reload(): Promise<Result<void>>;
+    /**
+     * 0.7.7 (fup-2026-202) — Lightweight in-place reload of registry + schemas.
+     * Triggered from `runExclusive` when `schemaStore.isStale()` reports drift
+     * (another process edited the schema/registry files since our last load).
+     *
+     * Does NOT reset the backend or git layer — only the in-memory schema and
+     * registry refs are swapped. Cheap enough to run as a defensive check on
+     * every write entry; the staleness probe (a handful of fstat calls) takes
+     * microseconds and the actual reload only fires when files actually
+     * changed. Failure path: log and proceed with the stale schema rather than
+     * blocking the write — a rare case (schema deleted mid-flight) where doing
+     * nothing is the lesser harm.
+     */
+    private reloadSchemasIfStale;
+    health(): HealthReport;
+    /**
+     * Size of the .git directory on disk, in bytes. Cached for 60s since a full
+     * recursive walk is O(size) and maad_health may be polled frequently. Returns
+     * null if git is unavailable. Best-effort: filesystem errors return null.
+     */
+    private probeRepoSize;
+    /**
+     * Synchronous "is the working tree clean" probe. Uses simple-git's
+     * status() — fast enough for health reporting. Returns null if git is
+     * unavailable. Best-effort: errors return null.
+     *
+     * Note: simple-git's status() is async, but we cache the most recent
+     * result on a health() call so maad_health stays synchronous.
+     */
+    private probeGitClean;
+    /**
+     * Refresh the cached git-clean flag. Called on demand (e.g. from an async
+     * path that awaits the status) and in the background by probeGitClean
+     * fallback.
+     */
+    refreshGitClean(): Promise<boolean | null>;
+    /**
+     * Free space on the volume holding projectRoot, in megabytes. Uses
+     * fs.statfsSync which is available on Node 18+. Returns null on error
+     * (e.g. unsupported filesystem, permissions).
+     */
+    private probeDiskHeadroom;
+    /**
+     * Test/drain accessor for the write mutex's current queue depth (held + waiting).
+     * Used by the lifecycle drain loop (0.4.1 H7) and the concurrency test suite.
+     */
+    writeQueueDepth(): number;
+    getStartupRecovery(): string[];
+    close(): void;
+    private ctx;
+    /**
+     * 0.7.0 — Set the identity slot used by the next git commit under the
+     * write mutex. Caller MUST be inside `runExclusive` so no concurrent
+     * writer can stomp the slot. `withEngine` (MCP layer) brackets set/clear
+     * around each write handler; clear with setCommitIdentity(undefined).
+     */
+    setCommitIdentity(identity: import('../git/commit.js').CommitIdentity | undefined): void;
+    private assertInit;
+    indexAll(opts?: {
+        force?: boolean;
+    }): Promise<import("./types.js").IndexResult>;
+    indexFile(absolutePath: FilePath): Promise<Result<ExtractionResult>>;
+    reindex(opts?: {
+        docId?: DocId;
+        force?: boolean;
+    }): Promise<Result<import("./types.js").IndexResult>>;
+    getDocument(id: DocId, depth: 'hot' | 'warm' | 'cold', blockIdOrHeading?: string): Promise<Result<import("./types.js").GetResult>>;
+    findDocuments(query: import('../types.js').DocumentQuery): Result<import("./types.js").FindResult>;
+    searchObjects(query: import('../types.js').ObjectQuery): Result<import("./types.js").SearchResult>;
+    listRelated(id: DocId, direction: 'outgoing' | 'incoming' | 'both', types?: DocType[]): Result<import("./types.js").RelatedResult>;
+    describe(): import("./types.js").DescribeResult;
+    summary(): import("./types.js").SummaryResult;
+    getSchema(dt: DocType): SchemaDefinition | undefined;
+    schemaInfo(dt: DocType): Result<import("./types.js").SchemaInfoResult>;
+    aggregate(query: import('./types.js').AggregateQuery): Result<import("./types.js").AggregateResult>;
+    join(query: import('./types.js').JoinQuery): Result<import("./types.js").JoinResult>;
+    verifyField(id: DocId, field: string, expected: unknown): Promise<Result<import("./types.js").VerifyResult>>;
+    verifyCount(dt: DocType, expectedCount: number, filters?: Record<string, import('../types.js').FilterCondition>): Result<import("./types.js").VerifyResult>;
+    changesSince(query: import('./types.js').ChangesSinceQuery): Result<import("./types.js").ChangesPage>;
+    getDocumentFull(id: DocId): Promise<Result<import("./types.js").GetFullResult>>;
+    createDocument(dt: DocType, fields: Record<string, unknown>, body?: string, customDocId?: string): Promise<{
+        ok: false;
+        errors: import("../errors.js").MaadError[];
+    } | {
+        ok: true;
+        value: unknown;
+    }>;
+    updateDocument(id: DocId, fields?: Record<string, unknown>, body?: string, appendBody?: string, expectedVersion?: number): Promise<{
+        ok: false;
+        errors: import("../errors.js").MaadError[];
+    } | {
+        ok: true;
+        value: unknown;
+    }>;
+    deleteDocument(id: DocId, mode: 'soft' | 'hard'): Promise<{
+        ok: false;
+        errors: import("../errors.js").MaadError[];
+    } | {
+        ok: true;
+        value: unknown;
+    }>;
+    bulkCreate(records: import('./types.js').BulkCreateInput[]): Promise<{
+        ok: false;
+        errors: import("../errors.js").MaadError[];
+    } | {
+        ok: true;
+        value: unknown;
+    }>;
+    bulkUpdate(updates: import('./types.js').BulkUpdateInput[]): Promise<{
+        ok: false;
+        errors: import("../errors.js").MaadError[];
+    } | {
+        ok: true;
+        value: unknown;
+    }>;
+    validate(docId?: DocId, options?: maintenance.ValidateOptions): Promise<Result<import("./types.js").ValidationReport>>;
+    history(id: DocId, opts?: {
+        limit?: number;
+        since?: string;
+    }): Promise<Result<import("../types.js").ParsedCommit[]>>;
+    diff(id: DocId, from: string, to?: string): Promise<Result<import("../types.js").DiffResult>>;
+    snapshot(id: DocId, at: string): Promise<Result<import("../types.js").SnapshotResult>>;
+    audit(opts?: {
+        since?: string;
+        until?: string;
+        docType?: DocType;
+    }): Promise<Result<import("../types.js").AuditEntry[]>>;
+    getBackend(): MaadBackend;
+    getRegistry(): Registry;
+    getGitLayer(): GitLayer | null;
+    getProjectRoot(): string;
+}
+//# sourceMappingURL=index.d.ts.map

package/dist/engine/index.d.ts.map

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