@maadb/core 0.0.1 → 0.7.9

package/dist/git/snapshot.js

@@ -0,0 +1,65 @@
+// ============================================================================
+// Git Snapshot Reader
+// Reads a document as it existed at a specific commit or date.
+// ============================================================================
+import { parseMatter } from '../parser/matter.js';
+import { commitSha as toCommitSha, } from '../types.js';
+export async function getSnapshot(git, filePath, docId, at) {
+    // Resolve 'at' to a commit SHA
+    let sha;
+    let timestamp;
+    if (/^[0-9a-f]{6,40}$/i.test(at)) {
+        // Already a SHA
+        sha = at;
+        try {
+            const info = await git.raw(['log', '-1', '--format=%aI', sha]);
+            timestamp = info.trim();
+        }
+        catch {
+            return null;
+        }
+    }
+    else {
+        // Treat as a date — find the last commit before that date
+        try {
+            const result = await git.raw([
+                'log', '-1', `--before=${at}`, '--format=%H|%aI', '--', filePath,
+            ]);
+            if (!result.trim())
+                return null;
+            const parts = result.trim().split('|');
+            sha = parts[0];
+            timestamp = parts[1];
+        }
+        catch {
+            return null;
+        }
+    }
+    // Read file content at that commit
+    let content;
+    try {
+        content = await git.show(`${sha}:${filePath}`);
+    }
+    catch {
+        return null;
+    }
+    // Parse frontmatter and body
+    let frontmatter = {};
+    let body = content;
+    try {
+        const parsed = parseMatter(content);
+        frontmatter = parsed.data;
+        body = parsed.content.trim();
+    }
+    catch {
+        // If parsing fails, return raw content as body
+    }
+    return {
+        docId,
+        commit: toCommitSha(sha),
+        timestamp,
+        frontmatter,
+        body,
+    };
+}
+//# sourceMappingURL=snapshot.js.map

package/dist/git/snapshot.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"snapshot.js","sourceRoot":"","sources":["../../src/git/snapshot.ts"],"names":[],"mappings":"AAAA,+EAA+E;AAC/E,sBAAsB;AACtB,+DAA+D;AAC/D,+EAA+E;AAG/E,OAAO,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAClD,OAAO,EACL,SAAS,IAAI,WAAW,GAIzB,MAAM,aAAa,CAAC;AAErB,MAAM,CAAC,KAAK,UAAU,WAAW,CAC/B,GAAc,EACd,QAAgB,EAChB,KAAY,EACZ,EAAU;IAEV,+BAA+B;IAC/B,IAAI,GAAW,CAAC;IAChB,IAAI,SAAiB,CAAC;IAEtB,IAAI,mBAAmB,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE,CAAC;QACjC,gBAAgB;QAChB,GAAG,GAAG,EAAE,CAAC;QACT,IAAI,CAAC;YACH,MAAM,IAAI,GAAG,MAAM,GAAG,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,IAAI,EAAE,cAAc,EAAE,GAAG,CAAC,CAAC,CAAC;YAC/D,SAAS,GAAG,IAAI,CAAC,IAAI,EAAE,CAAC;QAC1B,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,IAAI,CAAC;QACd,CAAC;IACH,CAAC;SAAM,CAAC;QACN,0DAA0D;QAC1D,IAAI,CAAC;YACH,MAAM,MAAM,GAAG,MAAM,GAAG,CAAC,GAAG,CAAC;gBAC3B,KAAK,EAAE,IAAI,EAAE,YAAY,EAAE,EAAE,EAAE,iBAAiB,EAAE,IAAI,EAAE,QAAQ;aACjE,CAAC,CAAC;YACH,IAAI,CAAC,MAAM,CAAC,IAAI,EAAE;gBAAE,OAAO,IAAI,CAAC;YAChC,MAAM,KAAK,GAAG,MAAM,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;YACvC,GAAG,GAAG,KAAK,CAAC,CAAC,CAAE,CAAC;YAChB,SAAS,GAAG,KAAK,CAAC,CAAC,CAAE,CAAC;QACxB,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,IAAI,CAAC;QACd,CAAC;IACH,CAAC;IAED,mCAAmC;IACnC,IAAI,OAAe,CAAC;IACpB,IAAI,CAAC;QACH,OAAO,GAAG,MAAM,GAAG,CAAC,IAAI,CAAC,GAAG,GAAG,IAAI,QAAQ,EAAE,CAAC,CAAC;IACjD,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;IAED,6BAA6B;IAC7B,IAAI,WAAW,GAA4B,EAAE,CAAC;IAC9C,IAAI,IAAI,GAAG,OAAO,CAAC;IACnB,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,WAAW,CAAC,OAAO,CAAC,CAAC;QACpC,WAAW,GAAG,MAAM,CAAC,IAA+B,CAAC;QACrD,IAAI,GAAG,MAAM,CAAC,OAAO,CAAC,IAAI,EAAE,CAAC;IAC/B,CAAC;IAAC,MAAM,CAAC;QACP,+CAA+C;IACjD,CAAC;IAED,OAAO;QACL,KAAK;QACL,MAAM,EAAE,WAAW,CAAC,GAAG,CAAC;QACxB,SAAS;QACT,WAAW;QACX,IAAI;KACL,CAAC;AACJ,CAAC"}

package/dist/instance/config.d.ts

@@ -0,0 +1,19 @@
+import { type Result } from '../errors.js';
+import { type Role } from '../mcp/roles.js';
+export interface ProjectConfig {
+    name: string;
+    path: string;
+    role: Role;
+    description?: string;
+}
+export interface InstanceConfig {
+    name: string;
+    projects: ProjectConfig[];
+    source: 'file' | 'synthetic';
+    configPath?: string;
+}
+export declare function loadInstance(configPath: string): Promise<Result<InstanceConfig>>;
+export declare function validateInstance(data: Record<string, unknown>, configPath?: string): Result<InstanceConfig>;
+export declare function synthesizeLegacyInstance(projectPath: string, role: Role): InstanceConfig;
+export declare function getProject(instance: InstanceConfig, name: string): ProjectConfig | undefined;
+//# sourceMappingURL=config.d.ts.map

package/dist/instance/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../src/instance/config.ts"],"names":[],"mappings":"AAYA,OAAO,EAAiC,KAAK,MAAM,EAAE,MAAM,cAAc,CAAC;AAC1E,OAAO,EAAa,KAAK,IAAI,EAAE,MAAM,iBAAiB,CAAC;AAEvD,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,IAAI,CAAC;IACX,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,aAAa,EAAE,CAAC;IAC1B,MAAM,EAAE,MAAM,GAAG,WAAW,CAAC;IAC7B,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAID,wBAAsB,YAAY,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,cAAc,CAAC,CAAC,CA4BtF;AAED,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,UAAU,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC,cAAc,CAAC,CAuD3G;AAKD,wBAAgB,wBAAwB,CAAC,WAAW,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,GAAG,cAAc,CAQxF;AAED,wBAAgB,UAAU,CAAC,QAAQ,EAAE,cAAc,EAAE,IAAI,EAAE,MAAM,GAAG,aAAa,GAAG,SAAS,CAE5F"}

package/dist/instance/config.js

@@ -0,0 +1,107 @@
+// ============================================================================
+// Instance Config — loads and validates instance.yaml
+//
+// An Instance declares a set of projects that one MCP server serves.
+// Real instance.yaml is loaded from disk. A "synthetic" instance wraps a
+// single --project path so the legacy CLI path flows through the same code.
+// ============================================================================
+import { readFile } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import path from 'node:path';
+import { parseMatter } from '../parser/matter.js';
+import { ok, err, singleErr, maadError } from '../errors.js';
+import { parseRole } from '../mcp/roles.js';
+const VALID_PROJECT_NAME = /^[a-z][a-z0-9_-]*$/;
+export async function loadInstance(configPath) {
+    const resolved = path.resolve(configPath);
+    if (!existsSync(resolved)) {
+        return singleErr('INSTANCE_CONFIG_NOT_FOUND', `Instance config not found: ${resolved}`);
+    }
+    let raw;
+    try {
+        raw = await readFile(resolved, 'utf-8');
+    }
+    catch (e) {
+        const message = e instanceof Error ? e.message : 'Unknown read error';
+        return singleErr('FILE_READ_ERROR', `Failed to read instance config: ${message}`);
+    }
+    let data;
+    try {
+        if (raw.trimStart().startsWith('---')) {
+            data = parseMatter(raw).data;
+        }
+        else {
+            data = parseMatter(`---\n${raw}\n---`).data;
+        }
+    }
+    catch (e) {
+        const message = e instanceof Error ? e.message : 'Unknown parse error';
+        return singleErr('PARSE_ERROR', `Failed to parse instance YAML: ${message}`);
+    }
+    return validateInstance(data, resolved);
+}
+export function validateInstance(data, configPath) {
+    const errors = [];
+    const configDir = configPath ? path.dirname(configPath) : process.cwd();
+    if (typeof data.name !== 'string' || data.name.length === 0) {
+        errors.push(maadError('INSTANCE_CONFIG_INVALID', 'instance.name is required and must be a non-empty string'));
+    }
+    const name = typeof data.name === 'string' ? data.name : '';
+    if (!Array.isArray(data.projects) || data.projects.length === 0) {
+        errors.push(maadError('INSTANCE_CONFIG_INVALID', 'instance.projects must be a non-empty array'));
+        return err(errors);
+    }
+    const projects = [];
+    const seenNames = new Set();
+    for (let i = 0; i < data.projects.length; i++) {
+        const raw = data.projects[i];
+        const where = `projects[${i}]`;
+        if (typeof raw !== 'object' || raw === null) {
+            errors.push(maadError('INSTANCE_CONFIG_INVALID', `${where} must be an object`));
+            continue;
+        }
+        const pname = raw.name;
+        if (typeof pname !== 'string' || !VALID_PROJECT_NAME.test(pname)) {
+            errors.push(maadError('INSTANCE_CONFIG_INVALID', `${where}.name must match /^[a-z][a-z0-9_-]*$/ (got ${JSON.stringify(pname)})`));
+            continue;
+        }
+        if (seenNames.has(pname)) {
+            errors.push(maadError('INSTANCE_CONFIG_INVALID', `${where}.name "${pname}" is duplicated`));
+            continue;
+        }
+        seenNames.add(pname);
+        const ppath = raw.path;
+        if (typeof ppath !== 'string' || ppath.length === 0) {
+            errors.push(maadError('INSTANCE_CONFIG_INVALID', `${where}.path is required`));
+            continue;
+        }
+        const absPath = path.isAbsolute(ppath) ? ppath : path.resolve(configDir, ppath);
+        const role = parseRole(typeof raw.role === 'string' ? raw.role : undefined);
+        const project = { name: pname, path: absPath, role };
+        if (typeof raw.description === 'string')
+            project.description = raw.description;
+        projects.push(project);
+    }
+    if (errors.length > 0)
+        return err(errors);
+    const result = { name, projects, source: 'file' };
+    if (configPath)
+        result.configPath = configPath;
+    return ok(result);
+}
+// Synthetic single-project instance for legacy --project path.
+// Wraps a raw project path + role into the same InstanceConfig shape so
+// downstream code (pool, session) does not need two paths.
+export function synthesizeLegacyInstance(projectPath, role) {
+    const absPath = path.resolve(projectPath);
+    const basename = path.basename(absPath).toLowerCase().replace(/[^a-z0-9_-]/g, '-') || 'default';
+    return {
+        name: `${basename}-legacy`,
+        projects: [{ name: 'default', path: absPath, role }],
+        source: 'synthetic',
+    };
+}
+export function getProject(instance, name) {
+    return instance.projects.find((p) => p.name === name);
+}
+//# sourceMappingURL=config.js.map

package/dist/instance/config.js.map

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

package/dist/instance/pool.d.ts

@@ -0,0 +1,138 @@
+import { MaadEngine } from '../engine/index.js';
+import { type Result } from '../errors.js';
+import type { InstanceConfig, ProjectConfig } from './config.js';
+export interface InstanceDiff {
+    added: string[];
+    removed: string[];
+}
+export interface InstanceReloadStats {
+    lastReloadAt: Date | null;
+    reloadsAttempted: number;
+    reloadsSucceeded: number;
+    reloadsFailed: number;
+    projectsAdded: number;
+    projectsRemoved: number;
+}
+/**
+ * 0.7.3 (fup-2026-150) — Idle-timeout eviction Stage 1.
+ *
+ * Tracks last-touched-at + in-flight refcount per loaded engine. A background
+ * sweeper closes engines that have been idle longer than the configured
+ * timeout AND have zero in-flight ops. Caps memory growth in multi-tenant
+ * deployments where projects are touched once and never again.
+ *
+ * Stage 2 (LRU + hard cap) is fup-2026-151 — gated on Stage 1 evidence.
+ */
+export interface EvictionStats {
+    evictionsTotal: number;
+    lastEvictionAt: Date | null;
+    lastEvictionProjects: string[];
+    sweepsRun: number;
+    lastSweepAt: Date | null;
+}
+export interface IdleSweepConfig {
+    /** Idle timeout threshold in ms. 0 disables eviction (just tracks touch times). */
+    idleTimeoutMs: number;
+    /** Sweep interval in ms. */
+    sweepIntervalMs: number;
+}
+export declare class EnginePool {
+    private instance;
+    private engines;
+    private initPromises;
+    private reloadInFlight;
+    private stats;
+    private lastTouchedAt;
+    private refcount;
+    private sweepHandle;
+    private sweepConfig;
+    private evictionStats;
+    private nowFn;
+    constructor(instance: InstanceConfig);
+    /** Test seam — override the time source so sweeper logic is testable. */
+    setNowFn(fn: () => number): void;
+    getInstance(): InstanceConfig;
+    listProjects(): ProjectConfig[];
+    has(name: string): boolean;
+    reloadStats(): InstanceReloadStats;
+    get(name: string): Promise<Result<MaadEngine>>;
+    /**
+     * 0.7.3 — In-flight refcount. Caller increments before invoking the
+     * handler, decrements in finally. The idle sweeper refuses to evict any
+     * project with refcount > 0.
+     */
+    acquire(name: string): void;
+    release(name: string): void;
+    refcountFor(name: string): number;
+    lastTouchedFor(name: string): number | null;
+    private initEngine;
+    evict(name: string): Promise<void>;
+    /**
+     * 0.7.3 — Idle eviction sweep. Returns the names of projects evicted in
+     * this sweep. Skips projects with refcount > 0 (in-flight ops) and any
+     * project whose lastTouchedAt is missing (defensive — would mean it's not
+     * actually loaded). idleTimeoutMs=0 is a no-op (eviction disabled).
+     */
+    evictIdle(idleTimeoutMs: number): Promise<string[]>;
+    /**
+     * 0.7.3 — Start the background idle sweeper. Idempotent — calling twice
+     * replaces the existing schedule. Use stopIdleSweeper() during shutdown.
+     * Sweep timer is unref()'d so it never blocks process exit.
+     */
+    startIdleSweeper(config: IdleSweepConfig): void;
+    stopIdleSweeper(): void;
+    evictionStatsSnapshot(): EvictionStats;
+    idleSweepConfig(): IdleSweepConfig | null;
+    static readIdleSweepEnv(env?: NodeJS.ProcessEnv): IdleSweepConfig;
+    closeAll(): Promise<void>;
+    /**
+     * Sum of `writeQueueDepth()` across every initialized engine. Used by the
+     * shutdown drain loop to know when it's safe to exit. Uninitialized engines
+     * contribute 0 and are not lazy-initialized.
+     */
+    totalWriteQueueDepth(): number;
+    /**
+     * Atomic reload slot — acquired before any I/O (config parse), released
+     * after diff + stats are recorded. The orchestrator in
+     * `src/mcp/instance-reload.ts` holds this for the lifetime of the reload
+     * so concurrent callers fail fast with INSTANCE_RELOAD_IN_PROGRESS instead
+     * of racing to swap the instance ref.
+     *
+     * Returns false if a reload is already in progress or the instance is
+     * synthetic (tested separately so the error code can be distinguished).
+     */
+    tryBeginReload(): {
+        ok: true;
+    } | {
+        ok: false;
+        code: 'INSTANCE_RELOAD_SYNTHETIC' | 'INSTANCE_RELOAD_IN_PROGRESS';
+    };
+    /**
+     * Release the reload slot. Called by the orchestrator in a `finally` so
+     * success + failure paths both land here. Updates the success/failure
+     * counters + project-diff stats.
+     */
+    endReload(outcome: {
+        ok: true;
+        diff: InstanceDiff;
+    } | {
+        ok: false;
+    }): void;
+    /**
+     * Apply a parsed instance config: detect mutations (fail-fast, no partial),
+     * evict engines for removed projects, swap the internal instance ref.
+     * Must be called between `tryBeginReload` and `endReload` — does not manage
+     * the reload slot itself.
+     *
+     * Mutations (same name, different path or role) fail the whole reload with
+     * INSTANCE_MUTATION_UNSUPPORTED — no partial apply. The 0.9.0 eviction
+     * policy unlocks safe in-place project mutations.
+     */
+    applyDiff(newInstance: InstanceConfig): Promise<Result<InstanceDiff>>;
+    /**
+     * Swap the instance config without diff/eviction. Used by the reload
+     * orchestrator if it needs to keep downstream refs in sync, or by tests.
+     */
+    setInstance(newInstance: InstanceConfig): void;
+}
+//# sourceMappingURL=pool.d.ts.map

package/dist/instance/pool.d.ts.map

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