@maadb/core 0.0.1 → 0.7.9

package/dist/mcp/idempotency.js

@@ -0,0 +1,168 @@
+// ============================================================================
+// Idempotency Cache — dedupes retried writes per (project, tool, key).
+//
+// Scope intentionally per-project, not per-session: a client whose connection
+// drops mid-retry reconnects with a fresh session ID and re-issues the write.
+// Session-scoped cache would miss and create a duplicate. Collision across
+// unrelated clients is the client's responsibility (use UUIDs).
+//
+// Replay returns the original response body byte-for-byte, with a fresh `_meta`
+// envelope: { replayed: true, original_request_id, original_completed_at }.
+// Clients that ignore `_meta` see a normal successful response.
+//
+// Bounded: 10-minute TTL, 10k-entry LRU cap. Tunable via env. In-memory only —
+// process restart drops the cache; documented behavior.
+// ============================================================================
+const DEFAULT_TTL_MS = 10 * 60 * 1000;
+const DEFAULT_MAX_ENTRIES = 10_000;
+export class IdempotencyCache {
+    ttlMs;
+    maxEntries;
+    now;
+    // JS Map preserves insertion order; we exploit that for O(1) LRU:
+    // every successful get() reinserts the entry to move it to the tail.
+    entries = new Map();
+    constructor(opts = {}) {
+        this.ttlMs = opts.ttlMs ?? DEFAULT_TTL_MS;
+        this.maxEntries = opts.maxEntries ?? DEFAULT_MAX_ENTRIES;
+        this.now = opts.now ?? (() => Date.now());
+    }
+    /** Compose the cache key. Always use this — never pass raw strings. */
+    static composeKey(projectName, toolName, clientKey) {
+        return `${projectName}\u0000${toolName}\u0000${clientKey}`;
+    }
+    /**
+     * Return a cached entry if present and not expired, else null. Reinserts on
+     * hit so recent hits survive eviction.
+     */
+    get(key) {
+        const entry = this.entries.get(key);
+        if (!entry)
+            return null;
+        if (this.now() - entry.insertedAtMs > this.ttlMs) {
+            this.entries.delete(key);
+            return null;
+        }
+        // Bump recency: delete + reinsert moves to the Map's tail.
+        this.entries.delete(key);
+        this.entries.set(key, entry);
+        return entry;
+    }
+    /**
+     * Store a response. Evicts the least-recently-used entry if the cap is full.
+     * Only call this for successful responses — failures must not short-circuit
+     * retries.
+     */
+    put(key, entry) {
+        if (this.entries.has(key)) {
+            // Refresh existing entry
+            this.entries.delete(key);
+        }
+        this.entries.set(key, { ...entry, insertedAtMs: this.now() });
+        while (this.entries.size > this.maxEntries) {
+            const oldestKey = this.entries.keys().next().value;
+            if (oldestKey === undefined)
+                break;
+            this.entries.delete(oldestKey);
+        }
+    }
+    size() {
+        return this.entries.size;
+    }
+    clear() {
+        this.entries.clear();
+    }
+}
+// ---- Module-level singleton (same pattern as response.ts provenance) --------
+let cache = new IdempotencyCache();
+/** Replace the singleton cache — called once from server startup with env-derived config. */
+export function initIdempotencyCache(opts) {
+    cache = new IdempotencyCache(opts);
+}
+/** Access the current singleton. Never returns null. */
+export function getIdempotencyCache() {
+    return cache;
+}
+// ---- Config from env --------------------------------------------------------
+export function readIdempotencyEnv() {
+    const ttl = process.env.MAAD_IDEMPOTENCY_TTL_MS;
+    const max = process.env.MAAD_IDEMPOTENCY_MAX;
+    const opts = {};
+    if (ttl && !Number.isNaN(Number(ttl)))
+        opts.ttlMs = Number(ttl);
+    if (max && !Number.isNaN(Number(max)))
+        opts.maxEntries = Number(max);
+    return opts;
+}
+/**
+ * Returns true if the response body (parsed from content[0].text) has
+ * `ok: true`. Silent false on parse failure — never cache anything we can't
+ * confirm succeeded.
+ */
+export function isSuccessfulResponse(response) {
+    const first = response.content[0];
+    if (!first || first.type !== 'text')
+        return false;
+    try {
+        const parsed = JSON.parse(first.text);
+        return parsed.ok === true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Build a replay response: identical body to the cached original, plus a fresh
+ * `_meta` envelope identifying this as a replay. Clients that ignore `_meta`
+ * see a normal successful response.
+ */
+export function buildReplayResponse(cached, currentRequestId) {
+    const original = cached.response;
+    const first = original.content[0];
+    if (!first || first.type !== 'text')
+        return original;
+    let parsed;
+    try {
+        parsed = JSON.parse(first.text);
+    }
+    catch {
+        return original;
+    }
+    parsed._meta = {
+        request_id: currentRequestId,
+        replayed: true,
+        original_request_id: cached.originalRequestId,
+        original_completed_at: cached.originalCompletedAt,
+    };
+    return { content: [{ type: 'text', text: JSON.stringify(parsed) }] };
+}
+/**
+ * Wrapper for mutating tool handlers. If `clientKey` is provided, checks the
+ * cache for a prior completed call matching `(projectName, toolName, clientKey)`.
+ * On hit: returns the cached response with fresh replay metadata.
+ * On miss: runs `fn()`, caches if successful, returns the result.
+ *
+ * `currentRequestId` is the request ID for this specific call (used both for
+ * _meta on replays and as `originalRequestId` when caching a fresh response).
+ * H6 will supply a real request ID from the MCP wrapper; for now callers can
+ * pass `crypto.randomUUID()` to satisfy the signature.
+ */
+export async function withIdempotency(projectName, toolName, clientKey, currentRequestId, fn) {
+    if (!clientKey)
+        return fn();
+    const cacheKey = IdempotencyCache.composeKey(projectName, toolName, clientKey);
+    const cached = cache.get(cacheKey);
+    if (cached) {
+        return buildReplayResponse(cached, currentRequestId);
+    }
+    const response = await fn();
+    if (isSuccessfulResponse(response)) {
+        cache.put(cacheKey, {
+            response,
+            originalRequestId: currentRequestId,
+            originalCompletedAt: new Date().toISOString(),
+        });
+    }
+    return response;
+}
+//# sourceMappingURL=idempotency.js.map

package/dist/mcp/idempotency.js.map

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

package/dist/mcp/instance-reload.d.ts

@@ -0,0 +1,23 @@
+import type { Result } from '../errors.js';
+import type { InstanceCtx } from './ctx.js';
+export type InstanceReloadSource = 'tool' | 'sighup';
+export interface InstanceReloadResult {
+    source: InstanceReloadSource;
+    projectsAdded: string[];
+    projectsRemoved: string[];
+    sessionsCancelled: string[];
+    sessionsPruned: string[];
+    durationMs: number;
+}
+/**
+ * Run a full instance reload from the config file recorded on the live
+ * InstanceConfig. Emits progress + audit log lines around the critical steps.
+ *
+ * Error codes that flow back to the caller (tool wraps them as MCP responses):
+ *   - INSTANCE_RELOAD_SYNTHETIC  (synthetic instance, no config file)
+ *   - INSTANCE_RELOAD_IN_PROGRESS (another reload is active)
+ *   - INSTANCE_RELOAD_FAILED     (parse error, file read error, etc.)
+ *   - INSTANCE_MUTATION_UNSUPPORTED (existing project path/role changed)
+ */
+export declare function performInstanceReload(ctx: InstanceCtx, source: InstanceReloadSource): Promise<Result<InstanceReloadResult>>;
+//# sourceMappingURL=instance-reload.d.ts.map

package/dist/mcp/instance-reload.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"instance-reload.d.ts","sourceRoot":"","sources":["../../src/mcp/instance-reload.ts"],"names":[],"mappings":"AAeA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AAE3C,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AAI5C,MAAM,MAAM,oBAAoB,GAAG,MAAM,GAAG,QAAQ,CAAC;AAErD,MAAM,WAAW,oBAAoB;IACnC,MAAM,EAAE,oBAAoB,CAAC;IAC7B,aAAa,EAAE,MAAM,EAAE,CAAC;IACxB,eAAe,EAAE,MAAM,EAAE,CAAC;IAC1B,iBAAiB,EAAE,MAAM,EAAE,CAAC;IAC5B,cAAc,EAAE,MAAM,EAAE,CAAC;IACzB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED;;;;;;;;;GASG;AACH,wBAAsB,qBAAqB,CACzC,GAAG,EAAE,WAAW,EAChB,MAAM,EAAE,oBAAoB,GAC3B,OAAO,CAAC,MAAM,CAAC,oBAAoB,CAAC,CAAC,CA4GvC"}

package/dist/mcp/instance-reload.js

@@ -0,0 +1,126 @@
+// ============================================================================
+// Instance reload orchestrator — shared by maad_instance_reload tool and the
+// SIGHUP handler. Re-parses the instance config from disk, delegates the diff
+// + eviction to EnginePool.reloadInstance, then propagates the new config to
+// SessionRegistry and cancels / prunes sessions whose projects were removed.
+//
+// Both call sites (tool handler, SIGHUP handler) invoke this with a `source`
+// string that flows into the audit event so operators can tell apart
+// operator-initiated reloads from OS-signal reloads.
+//
+// Failure modes never leave the runtime half-applied: diff mutations are
+// detected + rejected before any eviction, and the instance ref swap happens
+// only after the pool has finished its part.
+// ============================================================================
+import { ok, singleErr } from '../errors.js';
+import { loadInstance } from '../instance/config.js';
+import { logInstanceReload, logInstanceReloadProgress } from '../logging.js';
+/**
+ * Run a full instance reload from the config file recorded on the live
+ * InstanceConfig. Emits progress + audit log lines around the critical steps.
+ *
+ * Error codes that flow back to the caller (tool wraps them as MCP responses):
+ *   - INSTANCE_RELOAD_SYNTHETIC  (synthetic instance, no config file)
+ *   - INSTANCE_RELOAD_IN_PROGRESS (another reload is active)
+ *   - INSTANCE_RELOAD_FAILED     (parse error, file read error, etc.)
+ *   - INSTANCE_MUTATION_UNSUPPORTED (existing project path/role changed)
+ */
+export async function performInstanceReload(ctx, source) {
+    const startedAt = Date.now();
+    // Acquire the reload slot FIRST, before any I/O — otherwise concurrent
+    // callers can both pass the in-progress check while one is still parsing
+    // its yaml. tryBeginReload also handles the synthetic-instance fast path
+    // so both checks live in one place.
+    const begin = ctx.pool.tryBeginReload();
+    if (!begin.ok) {
+        const message = begin.code === 'INSTANCE_RELOAD_SYNTHETIC'
+            ? 'Synthetic (legacy --project) instances cannot be reloaded. Start the server with --instance <path> to enable reload.'
+            : 'Another instance reload is already running. Retry once it completes.';
+        return singleErr(begin.code, message);
+    }
+    // From here on, every return path must call ctx.pool.endReload to release
+    // the slot and record success/failure stats.
+    let outcome = { ok: false };
+    try {
+        const configPath = ctx.instance.configPath;
+        if (!configPath) {
+            // Defense: file-source instances should always carry configPath. Treat
+            // missing as a failed reload rather than a silent no-op.
+            return singleErr('INSTANCE_RELOAD_FAILED', 'Instance has source="file" but no configPath recorded; cannot re-parse.');
+        }
+        logInstanceReloadProgress({ source, phase: 'start' });
+        // Re-parse the config file. Parse errors leave the running instance intact.
+        const loaded = await loadInstance(configPath);
+        if (!loaded.ok) {
+            const first = loaded.errors[0];
+            const detail = loaded.errors.map(e => `${e.code}: ${e.message}`).join('; ');
+            logInstanceReloadProgress({
+                source,
+                phase: 'failed',
+                code: first?.code ?? 'INSTANCE_RELOAD_FAILED',
+                message: detail,
+                durationMs: Date.now() - startedAt,
+            });
+            return singleErr('INSTANCE_RELOAD_FAILED', `Failed to load instance config from ${configPath}: ${detail}`);
+        }
+        const newInstance = loaded.value;
+        // Pool applies the diff: mutation check + eviction of removed engines.
+        const diffResult = await ctx.pool.applyDiff(newInstance);
+        if (!diffResult.ok) {
+            const first = diffResult.errors[0];
+            logInstanceReloadProgress({
+                source,
+                phase: 'failed',
+                code: first?.code ?? 'INSTANCE_RELOAD_FAILED',
+                message: first?.message ?? 'Apply diff failed',
+                durationMs: Date.now() - startedAt,
+            });
+            return diffResult;
+        }
+        const diff = diffResult.value;
+        // Propagate the new config to downstream refs that hold their own copy.
+        ctx.instance = newInstance;
+        ctx.sessions.setInstance(newInstance);
+        // Session fallout: single-mode sessions on removed projects → cancelled;
+        // multi-mode sessions → whitelist pruned (cancelled only if it drains).
+        const cancelled = [];
+        const pruned = [];
+        for (const name of diff.removed) {
+            cancelled.push(...ctx.sessions.cancelByProject(name));
+            const { prunedSessions, cancelledSessions } = ctx.sessions.pruneProjectFromWhitelist(name);
+            pruned.push(...prunedSessions);
+            cancelled.push(...cancelledSessions);
+        }
+        const durationMs = Date.now() - startedAt;
+        logInstanceReload({
+            source,
+            projectsAdded: diff.added.length,
+            projectsRemoved: diff.removed.length,
+            projectsAddedNames: diff.added,
+            projectsRemovedNames: diff.removed,
+            sessionsCancelled: cancelled.length,
+            sessionsPruned: pruned.length,
+            durationMs,
+        });
+        logInstanceReloadProgress({
+            source,
+            phase: 'complete',
+            projectsAdded: diff.added.length,
+            projectsRemoved: diff.removed.length,
+            durationMs,
+        });
+        outcome = { ok: true, diff };
+        return ok({
+            source,
+            projectsAdded: diff.added,
+            projectsRemoved: diff.removed,
+            sessionsCancelled: cancelled,
+            sessionsPruned: pruned,
+            durationMs,
+        });
+    }
+    finally {
+        ctx.pool.endReload(outcome);
+    }
+}
+//# sourceMappingURL=instance-reload.js.map

package/dist/mcp/instance-reload.js.map

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

package/dist/mcp/kinds.d.ts

@@ -0,0 +1,22 @@
+export type OperationKind = 'read' | 'write';
+export declare const READ_TOOLS: ReadonlySet<string>;
+export declare const WRITE_TOOLS: ReadonlySet<string>;
+export declare const ENGINE_LESS_TOOLS: ReadonlySet<string>;
+/**
+ * Returns the operation kind for a tool that flows through `withEngine`.
+ * Returns null for engine-less tools OR unknown names — callers must
+ * distinguish via {@link isEngineLess}.
+ */
+export declare function getKindForTool(name: string): OperationKind | null;
+/**
+ * True if the tool is instance/session-scoped and does not pass through
+ * `withEngine`. Callers using {@link getKindForTool} should check this
+ * before treating a null return as "missing annotation".
+ */
+export declare function isEngineLess(name: string): boolean;
+/**
+ * Every engine-bound tool name currently registered. Used by CI tests that
+ * cross-check against the MCP server's actual registrations to catch drift.
+ */
+export declare function allEngineToolNames(): string[];
+//# sourceMappingURL=kinds.d.ts.map

package/dist/mcp/kinds.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"kinds.d.ts","sourceRoot":"","sources":["../../src/mcp/kinds.ts"],"names":[],"mappings":"AAgBA,MAAM,MAAM,aAAa,GAAG,MAAM,GAAG,OAAO,CAAC;AAI7C,eAAO,MAAM,UAAU,EAAE,WAAW,CAAC,MAAM,CAiBzC,CAAC;AAIH,eAAO,MAAM,WAAW,EAAE,WAAW,CAAC,MAAM,CAQ1C,CAAC;AAKH,eAAO,MAAM,iBAAiB,EAAE,WAAW,CAAC,MAAM,CAchD,CAAC;AAqBH;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,aAAa,GAAG,IAAI,CAIjE;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAElD;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,IAAI,MAAM,EAAE,CAE7C"}

package/dist/mcp/kinds.js

@@ -0,0 +1,110 @@
+// ============================================================================
+// Operation kind metadata — every MCP tool that flows through `withEngine`
+// declares read vs write. Reads invoke the handler directly; writes wrap it
+// in `engine.runExclusive` so the per-engine FIFO mutex serializes them.
+//
+// The classification is the source of truth at the request boundary. The
+// engine itself no longer self-wraps its mutation methods (0.5.0 R4) — the
+// mutex lives at the MCP entry point where concurrency policy belongs.
+//
+// Missing annotations are caught at:
+//   - module load (disjointness assertion below)
+//   - runtime in `withEngine` (MISSING_OPERATION_KIND for any tool that
+//     passes through without a registered kind)
+//   - CI (tests/mcp/kinds.test.ts cross-checks against registered tools)
+// ============================================================================
+// Tools that flow through withEngine and do not mutate git / SQLite /
+// in-memory cache / filesystem state.
+export const READ_TOOLS = new Set([
+    'maad_get',
+    'maad_query',
+    'maad_search',
+    'maad_related',
+    'maad_schema',
+    'maad_aggregate',
+    'maad_verify',
+    'maad_join',
+    'maad_changes_since',
+    'maad_history',
+    'maad_audit',
+    'maad_scan',
+    'maad_summary',
+    'maad_describe',
+    'maad_validate',
+    'maad_health',
+]);
+// Tools that flow through withEngine and may mutate engine state. Must
+// acquire the write mutex.
+export const WRITE_TOOLS = new Set([
+    'maad_create',
+    'maad_update',
+    'maad_bulk_create',
+    'maad_bulk_update',
+    'maad_delete',
+    'maad_reindex',
+    'maad_reload',
+]);
+// Tools that do not flow through withEngine — they operate on session /
+// instance state only and never resolve an engine. OperationKind does not
+// apply. Listed here so kind-coverage assertions know to skip them.
+export const ENGINE_LESS_TOOLS = new Set([
+    'maad_projects',
+    'maad_use_project',
+    'maad_use_projects',
+    'maad_current_session',
+    'maad_instance_reload',
+    'maad_subscribe',
+    'maad_unsubscribe',
+    'maad_subscriptions',
+    'maad_issue_token',
+    'maad_revoke_token',
+    'maad_rotate_token',
+    'maad_list_tokens',
+    'maad_show_token',
+]);
+// Assert the three sets are disjoint. A tool belongs to exactly one bucket.
+// Runs at module load — a bad entry crashes the process at startup rather
+// than silently shipping.
+(function assertDisjoint() {
+    const seen = new Map();
+    const register = (bucket, names) => {
+        for (const name of names) {
+            const prev = seen.get(name);
+            if (prev) {
+                throw new Error(`kinds.ts: tool "${name}" listed in both "${prev}" and "${bucket}"`);
+            }
+            seen.set(name, bucket);
+        }
+    };
+    register('READ_TOOLS', READ_TOOLS);
+    register('WRITE_TOOLS', WRITE_TOOLS);
+    register('ENGINE_LESS_TOOLS', ENGINE_LESS_TOOLS);
+})();
+/**
+ * Returns the operation kind for a tool that flows through `withEngine`.
+ * Returns null for engine-less tools OR unknown names — callers must
+ * distinguish via {@link isEngineLess}.
+ */
+export function getKindForTool(name) {
+    if (READ_TOOLS.has(name))
+        return 'read';
+    if (WRITE_TOOLS.has(name))
+        return 'write';
+    return null;
+}
+/**
+ * True if the tool is instance/session-scoped and does not pass through
+ * `withEngine`. Callers using {@link getKindForTool} should check this
+ * before treating a null return as "missing annotation".
+ */
+export function isEngineLess(name) {
+    return ENGINE_LESS_TOOLS.has(name);
+}
+/**
+ * Every engine-bound tool name currently registered. Used by CI tests that
+ * cross-check against the MCP server's actual registrations to catch drift.
+ */
+export function allEngineToolNames() {
+    return [...READ_TOOLS, ...WRITE_TOOLS];
+}
+//# sourceMappingURL=kinds.js.map

package/dist/mcp/kinds.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"kinds.js","sourceRoot":"","sources":["../../src/mcp/kinds.ts"],"names":[],"mappings":"AAAA,+EAA+E;AAC/E,2EAA2E;AAC3E,4EAA4E;AAC5E,yEAAyE;AACzE,EAAE;AACF,yEAAyE;AACzE,2EAA2E;AAC3E,uEAAuE;AACvE,EAAE;AACF,qCAAqC;AACrC,iDAAiD;AACjD,wEAAwE;AACxE,gDAAgD;AAChD,yEAAyE;AACzE,+EAA+E;AAI/E,sEAAsE;AACtE,sCAAsC;AACtC,MAAM,CAAC,MAAM,UAAU,GAAwB,IAAI,GAAG,CAAC;IACrD,UAAU;IACV,YAAY;IACZ,aAAa;IACb,cAAc;IACd,aAAa;IACb,gBAAgB;IAChB,aAAa;IACb,WAAW;IACX,oBAAoB;IACpB,cAAc;IACd,YAAY;IACZ,WAAW;IACX,cAAc;IACd,eAAe;IACf,eAAe;IACf,aAAa;CACd,CAAC,CAAC;AAEH,uEAAuE;AACvE,2BAA2B;AAC3B,MAAM,CAAC,MAAM,WAAW,GAAwB,IAAI,GAAG,CAAC;IACtD,aAAa;IACb,aAAa;IACb,kBAAkB;IAClB,kBAAkB;IAClB,aAAa;IACb,cAAc;IACd,aAAa;CACd,CAAC,CAAC;AAEH,wEAAwE;AACxE,0EAA0E;AAC1E,oEAAoE;AACpE,MAAM,CAAC,MAAM,iBAAiB,GAAwB,IAAI,GAAG,CAAC;IAC5D,eAAe;IACf,kBAAkB;IAClB,mBAAmB;IACnB,sBAAsB;IACtB,sBAAsB;IACtB,gBAAgB;IAChB,kBAAkB;IAClB,oBAAoB;IACpB,kBAAkB;IAClB,mBAAmB;IACnB,mBAAmB;IACnB,kBAAkB;IAClB,iBAAiB;CAClB,CAAC,CAAC;AAEH,4EAA4E;AAC5E,0EAA0E;AAC1E,0BAA0B;AAC1B,CAAC,SAAS,cAAc;IACtB,MAAM,IAAI,GAAG,IAAI,GAAG,EAAkB,CAAC;IACvC,MAAM,QAAQ,GAAG,CAAC,MAAc,EAAE,KAA0B,EAAE,EAAE;QAC9D,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;YACzB,MAAM,IAAI,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;YAC5B,IAAI,IAAI,EAAE,CAAC;gBACT,MAAM,IAAI,KAAK,CAAC,mBAAmB,IAAI,qBAAqB,IAAI,UAAU,MAAM,GAAG,CAAC,CAAC;YACvF,CAAC;YACD,IAAI,CAAC,GAAG,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;QACzB,CAAC;IACH,CAAC,CAAC;IACF,QAAQ,CAAC,YAAY,EAAE,UAAU,CAAC,CAAC;IACnC,QAAQ,CAAC,aAAa,EAAE,WAAW,CAAC,CAAC;IACrC,QAAQ,CAAC,mBAAmB,EAAE,iBAAiB,CAAC,CAAC;AACnD,CAAC,CAAC,EAAE,CAAC;AAEL;;;;GAIG;AACH,MAAM,UAAU,cAAc,CAAC,IAAY;IACzC,IAAI,UAAU,CAAC,GAAG,CAAC,IAAI,CAAC;QAAE,OAAO,MAAM,CAAC;IACxC,IAAI,WAAW,CAAC,GAAG,CAAC,IAAI,CAAC;QAAE,OAAO,OAAO,CAAC;IAC1C,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,YAAY,CAAC,IAAY;IACvC,OAAO,iBAAiB,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;AACrC,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,kBAAkB;IAChC,OAAO,CAAC,GAAG,UAAU,EAAE,GAAG,WAAW,CAAC,CAAC;AACzC,CAAC"}

package/dist/mcp/lifecycle.d.ts

@@ -0,0 +1,8 @@
+import { MaadEngine } from '../engine.js';
+export interface StartupResult {
+    engine: MaadEngine;
+    warnings: string[];
+}
+export declare function startupEngine(projectRoot: string): Promise<StartupResult>;
+export declare function registerShutdownHooks(engine: MaadEngine | null, cleanup?: () => Promise<void>): void;
+//# sourceMappingURL=lifecycle.d.ts.map

package/dist/mcp/lifecycle.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lifecycle.d.ts","sourceRoot":"","sources":["../../src/mcp/lifecycle.ts"],"names":[],"mappings":"AAOA,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAI1C,MAAM,WAAW,aAAa;IAC5B,MAAM,EAAE,UAAU,CAAC;IACnB,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AAED,wBAAsB,aAAa,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,CAAC,CA6C/E;AAED,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,UAAU,GAAG,IAAI,EAAE,OAAO,CAAC,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAYpG"}

package/dist/mcp/lifecycle.js

@@ -0,0 +1,65 @@
+// ============================================================================
+// MCP Lifecycle — startup validation, engine init, shutdown hooks
+// Extracted from server.ts to keep server focused on transport.
+// ============================================================================
+import { existsSync } from 'node:fs';
+import path from 'node:path';
+import { MaadEngine } from '../engine.js';
+import { logger } from '../engine/logger.js';
+import { ensureProjectSkills } from '../skills-scaffold.js';
+export async function startupEngine(projectRoot) {
+    const resolved = path.resolve(projectRoot);
+    const warnings = [];
+    // Validate project exists
+    if (!existsSync(resolved)) {
+        throw new Error(`Project directory not found: ${resolved}`);
+    }
+    // Init engine — self-heals _registry, _schema, _backend on empty projects
+    const engine = new MaadEngine();
+    const initResult = await engine.init(resolved);
+    if (!initResult.ok) {
+        const messages = initResult.errors.map(e => `${e.code}: ${e.message}`).join('; ');
+        throw new Error(`Engine initialization failed: ${messages}`);
+    }
+    // Ensure _skills/ guide files exist for the agent. Non-blocking: a failed
+    // write (permissions, read-only FS) logs a warning but does not crash the
+    // server — engine is already up and usable without the skills.
+    if (!engine.isReadOnly()) {
+        const skillsResult = ensureProjectSkills(resolved);
+        if (skillsResult.created.length > 0) {
+            logger.info('lifecycle', 'startup', `Scaffolded skills: ${skillsResult.created.join(', ')}`);
+        }
+        for (const e of skillsResult.errors) {
+            logger.bestEffort('lifecycle', 'startup', `Failed to write ${e.file}: ${e.message}`);
+            warnings.push(`skills scaffold: ${e.file} — ${e.message}`);
+        }
+    }
+    // Check for recovery actions
+    const recovery = engine.getStartupRecovery();
+    if (recovery.length > 0) {
+        for (const action of recovery) {
+            logger.info('lifecycle', 'startup', action);
+            warnings.push(action);
+        }
+    }
+    // Log health
+    const health = engine.health();
+    logger.info('lifecycle', 'startup', `Engine ready: ${health.totalDocuments} docs, ${health.registeredTypes} types, git: ${health.gitAvailable}`);
+    return { engine, warnings };
+}
+export function registerShutdownHooks(engine, cleanup) {
+    // Legacy shim retained for any caller that still uses the single-engine
+    // flow. The modern path is installSignalHandlers(target, opts) from
+    // src/mcp/shutdown.ts with pool + rate limiter. Server.ts uses that path.
+    const shutdown = async () => {
+        logger.info('lifecycle', 'shutdown', 'Shutting down...');
+        if (engine)
+            engine.close();
+        if (cleanup)
+            await cleanup();
+        process.exit(0);
+    };
+    process.on('SIGINT', shutdown);
+    process.on('SIGTERM', shutdown);
+}
+//# sourceMappingURL=lifecycle.js.map

package/dist/mcp/lifecycle.js.map

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

package/dist/mcp/notifications.d.ts

@@ -0,0 +1,87 @@
+import type { InstanceCtx } from './ctx.js';
+/**
+ * Event shape emitted on durable writes. Used both as the payload mapped into
+ * MCP's `notifications/resources/updated` and as the match target for
+ * per-session filters.
+ */
+export interface ChangeEvent {
+    action: 'create' | 'update' | 'delete';
+    docId: string;
+    docType: string;
+    project: string;
+    updatedAt: string;
+}
+/**
+ * Callback that pushes a ChangeEvent to a single MCP session's client. The
+ * transport layer (HTTP or stdio) registers this closure when it builds the
+ * per-session McpServer. Failures are logged but never thrown — a broken
+ * notifier channel must not kill the write that triggered it.
+ */
+export type Notifier = (event: ChangeEvent) => Promise<void>;
+/**
+ * Register a notifier for a session. Called by the transport once the
+ * per-session McpServer is connected and ready to emit. Overwrites any
+ * prior registration for the same sessionId (transport reconnect path).
+ */
+export declare function registerNotifier(sessionId: string, fn: Notifier): void;
+/**
+ * Remove a notifier. Called when a session is destroyed (SessionRegistry
+ * close handler fans this out). Safe to call with an unknown sessionId.
+ */
+export declare function unregisterNotifier(sessionId: string): void;
+/**
+ * Current count of registered notifiers. Used by maad_health telemetry and
+ * by zero-overhead fast-path detection in `notifyWrite`.
+ */
+export declare function notifierCount(): number;
+/**
+ * Test hook — drops every registered notifier. Production code never calls
+ * this; vitest suites that reuse the process need it between cases.
+ */
+export declare function __resetNotifiers(): void;
+/**
+ * Fan-out entry point called by MCP write tool handlers after a successful
+ * durable commit. Iterates sessions with subscriptions, matches the filter,
+ * and invokes each session's notifier. Zero overhead when no session has a
+ * subscription (the count check bypasses the iteration).
+ *
+ * Caller MUST only invoke this when `writeDurable === true` on the engine
+ * result — the durability gate is upstream, not here. Delete operations
+ * should pass `action: 'delete'` and the docType recorded before deletion.
+ */
+export declare function notifyWrite(ctx: InstanceCtx, event: ChangeEvent): Promise<void>;
+/**
+ * 0.6.12 — Inventory of active subscriptions across an instance. Produced
+ * by `maad_subscriptions` (admin-only). Extracted here so the aggregation
+ * logic is unit-testable without spinning up a full MCP server.
+ *
+ * `byProject` reflects "who would receive an event for project X": single-mode
+ * sessions bin under their activeProject; multi-mode sessions without an
+ * explicit project filter bin under every whitelisted project; sessions with
+ * an explicit filter bin only under that project.
+ *
+ * `byDocType` uses `*` as the any-type bucket (subscribers that omitted the
+ * docTypes filter) so admins can tell at a glance how many "firehose" vs
+ * "type-narrowed" subscribers are active.
+ */
+export interface SubscriptionInventoryEntry {
+    sessionId: string;
+    mode: string | null;
+    activeProject: string | null;
+    whitelist: string[] | null;
+    subscription: {
+        docTypes: string[] | null;
+        project: string | null;
+        createdAt: string;
+    };
+    bindingSource: string | null;
+    lastActivityAt: string;
+}
+export interface SubscriptionInventory {
+    totalSubscriptions: number;
+    subscriptions: SubscriptionInventoryEntry[];
+    byProject: Record<string, number>;
+    byDocType: Record<string, number>;
+}
+export declare function collectSubscriptions(sessions: InstanceCtx['sessions']): SubscriptionInventory;
+//# sourceMappingURL=notifications.d.ts.map