@maadb/core 0.0.1 → 0.7.10-rc.3

package/dist/mcp/server.d.ts

@@ -0,0 +1,33 @@
+export type Transport = 'stdio' | 'http' | 'unix';
+export interface HttpServeOptions {
+    host: string;
+    port: number;
+    maxBodyBytes: number;
+    headersTimeoutMs: number;
+    requestTimeoutMs: number;
+    keepAliveTimeoutMs: number;
+    trustProxy: boolean;
+    idleMs: number;
+    authToken?: string | undefined;
+    /**
+     * 0.7.5 (fup-2026-148) — Unix domain socket path. When set with
+     * transport='unix' (or 'http' with this populated), the server binds
+     * to this socket instead of host:port. Same MCP protocol; trusted-host
+     * deploy pattern.
+     */
+    socketPath?: string | undefined;
+    /** Socket file mode (octal). Default 0o660. */
+    socketMode?: number | undefined;
+}
+export interface ServeOptions {
+    projectRoot?: string | undefined;
+    instancePath?: string | undefined;
+    role?: string | undefined;
+    dryRun?: boolean | undefined;
+    toolAllowlist?: string[] | undefined;
+    provenance?: string | undefined;
+    transport?: Transport | undefined;
+    http?: HttpServeOptions | undefined;
+}
+export declare function startServer(opts: ServeOptions): Promise<void>;
+//# sourceMappingURL=server.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../../src/mcp/server.ts"],"names":[],"mappings":"AA2CA,MAAM,MAAM,SAAS,GAAG,OAAO,GAAG,MAAM,GAAG,MAAM,CAAC;AAElD,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,YAAY,EAAE,MAAM,CAAC;IACrB,gBAAgB,EAAE,MAAM,CAAC;IACzB,gBAAgB,EAAE,MAAM,CAAC;IACzB,kBAAkB,EAAE,MAAM,CAAC;IAC3B,UAAU,EAAE,OAAO,CAAC;IACpB,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC/B;;;;;OAKG;IACH,UAAU,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAChC,+CAA+C;IAC/C,UAAU,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CACjC;AAED,MAAM,WAAW,YAAY;IAC3B,WAAW,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACjC,YAAY,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAClC,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC1B,MAAM,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IAC7B,aAAa,CAAC,EAAE,MAAM,EAAE,GAAG,SAAS,CAAC;IACrC,UAAU,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAChC,SAAS,CAAC,EAAE,SAAS,GAAG,SAAS,CAAC;IAClC,IAAI,CAAC,EAAE,gBAAgB,GAAG,SAAS,CAAC;CACrC;AAED,wBAAsB,WAAW,CAAC,IAAI,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC,CAuOnE"}

package/dist/mcp/server.js

@@ -0,0 +1,252 @@
+// ============================================================================
+// MCP Server — transport setup and tool registration
+// Lifecycle, config, and guardrails are extracted into separate modules.
+// ============================================================================
+import { createRequire } from 'node:module';
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { buildConfig } from './config.js';
+import { startHttpTransport } from './transport/http.js';
+import { initTransportTelemetry, recordSessionClose } from './transport/telemetry.js';
+const require = createRequire(import.meta.url);
+const pkg = require('../../package.json');
+import { setGuardrailConfig } from './guardrails.js';
+import { setProvenanceMode } from './response.js';
+import { initIdempotencyCache, readIdempotencyEnv } from './idempotency.js';
+import { initRateLimiter, readRateLimitEnv } from './rate-limit.js';
+import { initMemoryPressureWatcher, readMemoryPressureEnv, stopMemoryPressureWatcher } from './memory-pressure.js';
+import { initLogging, readLoggingEnv, logOpsChannelReady } from '../logging.js';
+import { installSignalHandlers } from './shutdown.js';
+import { installReloadSignalHandler } from './reload-signal.js';
+import { getRateLimiter } from './rate-limit.js';
+import { logger } from '../engine/logger.js';
+import { synthesizeLegacyInstance, loadInstance } from '../instance/config.js';
+import { EnginePool } from '../instance/pool.js';
+import { SessionRegistry } from '../instance/session.js';
+import { parseRole } from './roles.js';
+import { TokenStore } from '../auth/token-store.js';
+import { checkHttpAuthAtBoot } from './transport/auth.js';
+import { existsSync } from 'node:fs';
+import path from 'node:path';
+import * as discoverTools from './tools/discover.js';
+import * as readTools from './tools/read.js';
+import * as writeTools from './tools/write.js';
+import * as auditTools from './tools/audit.js';
+import * as maintainTools from './tools/maintain.js';
+import * as backupTools from './tools/backup.js';
+import * as instanceTools from './tools/instance.js';
+import * as authTools from './tools/auth.js';
+export async function startServer(opts) {
+    // Resolve the instance: either loaded from instance.yaml or synthesized
+    // from a legacy --project path so existing clients upgrade without changes.
+    let instance;
+    if (opts.instancePath) {
+        const loaded = await loadInstance(opts.instancePath);
+        if (!loaded.ok) {
+            const messages = loaded.errors.map(e => `${e.code}: ${e.message}`).join('; ');
+            console.error(`MAAD MCP: instance config invalid: ${messages}`);
+            process.exit(1);
+        }
+        instance = loaded.value;
+    }
+    else if (opts.projectRoot) {
+        const config = buildConfig({ projectRoot: opts.projectRoot, role: opts.role, dryRun: opts.dryRun, toolAllowlist: opts.toolAllowlist, provenance: opts.provenance });
+        instance = synthesizeLegacyInstance(config.projectRoot, parseRole(config.role));
+    }
+    else {
+        console.error('MAAD MCP: must provide --project or --instance (or MAAD_PROJECT / MAAD_INSTANCE env var)');
+        process.exit(1);
+    }
+    // Build global guardrail + provenance state from opts
+    const dryRun = opts.dryRun ?? (process.env.MAAD_DRY_RUN === '1' || process.env.MAAD_DRY_RUN === 'true');
+    const provenance = opts.provenance ?? process.env.MAAD_PROV ?? 'off';
+    setGuardrailConfig({ dryRun, toolAllowlist: opts.toolAllowlist });
+    setProvenanceMode(provenance);
+    initLogging(readLoggingEnv());
+    // 0.7.3 (fup-2026-096) — emit one self-check line so deploy validation can
+    // confirm the ops channel is wired before any tool call. If this line is
+    // missing in journalctl/stderr, no other ops event (commit_failed,
+    // rate_limited, validation_warning) will surface either.
+    const loggingEnv = readLoggingEnv();
+    logOpsChannelReady({
+        destination: loggingEnv.pretty ? 'pretty' : 'stderr',
+        level: loggingEnv.level ?? 'info',
+        pid: process.pid,
+    });
+    initIdempotencyCache(readIdempotencyEnv());
+    initRateLimiter(readRateLimitEnv());
+    // 0.7.10 P5 — V8 heap-pressure sampler. Defaults: 60s interval, 0.8 ratio
+    // threshold, 5min fire cooldown. Set MAAD_MEMORY_PRESSURE_INTERVAL_MS=0 to
+    // disable. Emits degraded-severity ops events when V8 heap approaches the
+    // cgroup-driven heap cap so OOMs are visible pre-crash.
+    initMemoryPressureWatcher(readMemoryPressureEnv());
+    // 0.7.0 — Load the token registry (HTTP+file mode) or null-out for stdio/synthetic.
+    // Boot-mode enforcement happens in the HTTP branch below; in stdio/synthetic
+    // the registry is irrelevant (no bearer channel). Parse errors at startup
+    // refuse to boot — operator sees the exact file path + js-yaml error.
+    let tokens = null;
+    if (instance.source === 'file' && instance.configPath) {
+        const instanceRoot = path.dirname(instance.configPath);
+        const loaded = await TokenStore.load(instanceRoot);
+        if (!loaded.ok) {
+            const messages = loaded.errors.map(e => `${e.code}: ${e.message}`).join('; ');
+            console.error(`MAAD MCP: token registry invalid: ${messages}`);
+            process.exit(1);
+        }
+        tokens = loaded.value;
+    }
+    // Build the instance-scoped runtime context
+    const pool = new EnginePool(instance);
+    // 0.7.3 (fup-2026-150) — start idle-timeout sweeper. Defaults: 30 min idle,
+    // 60s sweep. Set MAAD_PROJECT_IDLE_TIMEOUT_MS=0 to disable.
+    pool.startIdleSweeper(EnginePool.readIdleSweepEnv());
+    const sessions = new SessionRegistry(instance);
+    const ctx = { instance, pool, sessions, tokens };
+    // For the legacy synthetic path we eager-init the single engine so the
+    // first tool call is fast and any startup errors surface immediately. In
+    // real instance mode, projects are lazy — engines init on first use.
+    if (instance.source === 'synthetic') {
+        const eager = await pool.get('default');
+        if (!eager.ok) {
+            const messages = eager.errors.map(e => `${e.code}: ${e.message}`).join('; ');
+            console.error(`MAAD MCP: engine initialization failed: ${messages}`);
+            process.exit(1);
+        }
+    }
+    // Tool registration factory. Stdio creates one server for the process.
+    // HTTP creates a fresh server per session (per SDK example pattern) — tool
+    // registration is cheap (schema only, no engine work), so the per-session
+    // cost is negligible and isolation is cleaner.
+    const legacyRole = instance.source === 'synthetic' ? parseRole(opts.role) : 'admin';
+    const buildMcpServer = () => {
+        const server = new McpServer({ name: 'maad', version: pkg.version });
+        let toolCount = 0;
+        if (instance.source === 'file') {
+            toolCount += instanceTools.register(server, ctx);
+        }
+        toolCount += discoverTools.register(server, ctx);
+        toolCount += readTools.register(server, ctx);
+        toolCount += auditTools.register(server, ctx);
+        if (legacyRole === 'writer' || legacyRole === 'admin') {
+            toolCount += writeTools.register(server, ctx);
+        }
+        if (legacyRole === 'admin') {
+            toolCount += maintainTools.register(server, ctx);
+            toolCount += backupTools.register(server, ctx);
+            // maad_instance_reload always registers for admin, even on synthetic
+            // instances — handler rejects synthetic with INSTANCE_RELOAD_SYNTHETIC
+            // rather than an opaque "unknown tool" response.
+            toolCount += instanceTools.registerReload(server, ctx);
+            // 0.7.0 — admin token registry tools. Handler refuses if ctx.tokens is
+            // null (stdio/synthetic mode has no registry); registering always so
+            // synthetic clients get a clear TOKENS_FILE_MISSING error rather than
+            // an opaque "unknown tool" response.
+            toolCount += authTools.register(server, ctx);
+        }
+        return { server, toolCount };
+    };
+    const transportKind = opts.transport ?? 'stdio';
+    if (transportKind === 'http' || transportKind === 'unix') {
+        if (!opts.http) {
+            console.error(`MAAD MCP: --transport ${transportKind} requires HTTP/UDS config`);
+            process.exit(1);
+        }
+        if (transportKind === 'unix' && !opts.http.socketPath) {
+            console.error('MAAD MCP: --transport unix requires --unix-socket=<path> (or MAAD_UNIX_SOCKET env)');
+            process.exit(1);
+        }
+        // 0.7.0 — Legacy single-bearer mode hard-removed (dec-maadb-071). HTTP
+        // requires _auth/tokens.yaml with ≥1 active entry. Stale MAAD_AUTH_TOKEN
+        // env config surfaces a distinctive LEGACY_BEARER_REMOVED error so
+        // operators see the migration hint before chasing a generic boot failure.
+        // 0.7.5 — UDS transport reuses the same auth gate; bearer is still required
+        // (filesystem perms are defense-in-depth, not a replacement).
+        if (instance.source !== 'file' || !instance.configPath) {
+            console.error(`MAAD MCP: --transport ${transportKind} requires --instance (synthetic --project mode is stdio-only)`);
+            process.exit(1);
+        }
+        const instanceRoot = path.dirname(instance.configPath);
+        const storeExists = existsSync(path.join(instanceRoot, '_auth', 'tokens.yaml'));
+        const bootErr = checkHttpAuthAtBoot(tokens, storeExists, opts.http.authToken);
+        if (bootErr !== null) {
+            console.error(`MAAD MCP: ${bootErr}`);
+            process.exit(1);
+        }
+        // One-time registration log using a throwaway count from a probe server.
+        // In HTTP mode the real server instances are built per session.
+        const { toolCount } = buildMcpServer();
+        const transportLabel = transportKind === 'unix'
+            ? `unix:${opts.http.socketPath}`
+            : `http://${opts.http.host}:${opts.http.port}`;
+        logger.info('mcp', 'startup', `${toolCount} tools registered — instance "${instance.name}" (${instance.source}), ${instance.projects.length} project(s)${dryRun ? ' (dry-run)' : ''} [transport=${transportKind}, ${transportLabel}]`);
+        initTransportTelemetry(transportKind === 'unix'
+            ? { kind: 'unix', socketPath: opts.http.socketPath }
+            : { kind: 'http', host: opts.http.host, port: opts.http.port });
+        // Wire session-close fan-out: when a session is destroyed (for any
+        // reason — client DELETE, transport drop, idle sweep, shutdown), release
+        // its per-session rate-limit state and emit the session_close audit event
+        // with the measured duration. Additional handlers stack in registration order.
+        ctx.sessions.registerCloseHandler((sid, reason) => {
+            getRateLimiter().disposeSession(sid);
+            recordSessionClose({ session_id: sid, reason });
+        });
+        const handle = await startHttpTransport({
+            host: opts.http.host,
+            port: opts.http.port,
+            socketPath: transportKind === 'unix' ? opts.http.socketPath : undefined,
+            socketMode: transportKind === 'unix' ? opts.http.socketMode : undefined,
+            maxBodyBytes: opts.http.maxBodyBytes,
+            headersTimeoutMs: opts.http.headersTimeoutMs,
+            requestTimeoutMs: opts.http.requestTimeoutMs,
+            keepAliveTimeoutMs: opts.http.keepAliveTimeoutMs,
+            trustProxy: opts.http.trustProxy,
+            idleMs: opts.http.idleMs,
+            tokens: tokens,
+            sessions: ctx.sessions,
+            instance,
+            serverFactory: () => buildMcpServer().server,
+        });
+        installSignalHandlers({ pool, rateLimiter: getRateLimiter() }, {
+            finalCleanup: async () => {
+                stopMemoryPressureWatcher();
+                try {
+                    await handle.close();
+                }
+                catch { /* best-effort */ }
+            },
+        });
+        installReloadSignalHandler(ctx);
+        return;
+    }
+    // stdio — single server, single transport, lifetime of the process
+    initTransportTelemetry({ kind: 'stdio' });
+    const { server, toolCount } = buildMcpServer();
+    logger.info('mcp', 'startup', `${toolCount} tools registered — instance "${instance.name}" (${instance.source}), ${instance.projects.length} project(s)${dryRun ? ' (dry-run)' : ''}`);
+    // 0.6.11 — stdio live-notification notifier. stdio has exactly one session
+    // per process, synthesized lazily on first tool call. Register on create so
+    // the sid is known before we install the notifier. Unregister on close.
+    const { registerNotifier: regN, unregisterNotifier: unregN } = await import('./notifications.js');
+    ctx.sessions.registerCreateHandler((sid) => {
+        regN(sid, async (event) => {
+            await server.server.sendResourceUpdated({
+                uri: `maad://records/${event.docId}`,
+                ...{ action: event.action, docId: event.docId, docType: event.docType, project: event.project, updatedAt: event.updatedAt },
+            });
+        });
+    });
+    ctx.sessions.registerCloseHandler((sid) => { unregN(sid); });
+    installSignalHandlers({ pool, rateLimiter: getRateLimiter() }, {
+        finalCleanup: async () => {
+            stopMemoryPressureWatcher();
+            try {
+                await server.close();
+            }
+            catch { /* best-effort */ }
+        },
+    });
+    installReloadSignalHandler(ctx);
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    logger.info('mcp', 'startup', 'Server started on stdio');
+}
+//# sourceMappingURL=server.js.map

package/dist/mcp/server.js.map

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

package/dist/mcp/shutdown.d.ts

@@ -0,0 +1,32 @@
+import type { EnginePool } from '../instance/pool.js';
+import type { SessionRateLimiter } from './rate-limit.js';
+export type ShutdownState = 'running' | 'draining' | 'exiting';
+export interface DrainTarget {
+    pool: EnginePool;
+    rateLimiter: SessionRateLimiter;
+}
+export interface ShutdownOptions {
+    shutdownTimeoutMs?: number;
+    exit?: (code: number) => void;
+    installHandlers?: boolean;
+    finalCleanup?: () => Promise<void>;
+}
+export declare function getShutdownState(): ShutdownState;
+export declare function isShuttingDown(): boolean;
+/**
+ * Test hook — resets module state. NEVER call from production code.
+ */
+export declare function __resetShutdownState(): void;
+/**
+ * Begin shutdown. First call flips state to 'draining' and starts the drain
+ * loop. Second call short-circuits the wait and accelerates to exiting.
+ * Third+ calls are ignored.
+ */
+export declare function beginShutdown(target: DrainTarget, opts?: ShutdownOptions): Promise<void>;
+/**
+ * Install SIGTERM / SIGINT handlers that call beginShutdown on first hit and
+ * accelerate on the second. Call once from server startup. Tests bypass this
+ * by installing their own handlers or calling beginShutdown directly.
+ */
+export declare function installSignalHandlers(target: DrainTarget, opts?: ShutdownOptions): void;
+//# sourceMappingURL=shutdown.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"shutdown.d.ts","sourceRoot":"","sources":["../../src/mcp/shutdown.ts"],"names":[],"mappings":"AAiBA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AACtD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAC;AAG1D,MAAM,MAAM,aAAa,GAAG,SAAS,GAAG,UAAU,GAAG,SAAS,CAAC;AAE/D,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,UAAU,CAAC;IACjB,WAAW,EAAE,kBAAkB,CAAC;CACjC;AAED,MAAM,WAAW,eAAe;IAC9B,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAG3B,IAAI,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IAE9B,eAAe,CAAC,EAAE,OAAO,CAAC;IAE1B,YAAY,CAAC,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CACpC;AASD,wBAAgB,gBAAgB,IAAI,aAAa,CAEhD;AAED,wBAAgB,cAAc,IAAI,OAAO,CAExC;AAED;;GAEG;AACH,wBAAgB,oBAAoB,IAAI,IAAI,CAI3C;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAC3B,MAAM,EAAE,WAAW,EACnB,IAAI,GAAE,eAAoB,GACzB,OAAO,CAAC,IAAI,CAAC,CA6Ef;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,WAAW,EAAE,IAAI,GAAE,eAAoB,GAAG,IAAI,CAQ3F"}

package/dist/mcp/shutdown.js

@@ -0,0 +1,130 @@
+// ============================================================================
+// Shutdown state machine — running → draining → exiting.
+//
+// SIGTERM / SIGINT trigger DRAINING. New tool calls are rejected at the
+// `withEngine` entry with SHUTTING_DOWN. In-flight writes are given a bounded
+// window to complete (MAAD_SHUTDOWN_TIMEOUT_MS, default 10s). After drain or
+// timeout, EXITING closes engines, flushes audit, and process.exit(code).
+//
+// Second signal during DRAINING skips the wait and force-exits.
+//
+// Cooperative cancellation *inside* engine methods (AbortSignal threaded
+// through stage boundaries) is deferred to 0.8.5 and documented in gaps.md.
+// For 0.4.1: requests already executing run to completion; the drain waits
+// for them; clients see either their response or REQUEST_TIMEOUT if the
+// per-request ceiling was first.
+// ============================================================================
+import { getOpsLog } from '../logging.js';
+const DEFAULT_SHUTDOWN_TIMEOUT_MS = 10_000;
+const DRAIN_POLL_MS = 50;
+let state = 'running';
+let shutdownStartedAt = null;
+let shutdownPromise = null;
+export function getShutdownState() {
+    return state;
+}
+export function isShuttingDown() {
+    return state !== 'running';
+}
+/**
+ * Test hook — resets module state. NEVER call from production code.
+ */
+export function __resetShutdownState() {
+    state = 'running';
+    shutdownStartedAt = null;
+    shutdownPromise = null;
+}
+/**
+ * Begin shutdown. First call flips state to 'draining' and starts the drain
+ * loop. Second call short-circuits the wait and accelerates to exiting.
+ * Third+ calls are ignored.
+ */
+export function beginShutdown(target, opts = {}) {
+    const log = getOpsLog();
+    if (state === 'exiting') {
+        // Already on the way out — nothing to do.
+        return shutdownPromise ?? Promise.resolve();
+    }
+    if (state === 'draining') {
+        // Second signal: accelerate.
+        log.warn({ event: 'shutdown_forced' }, 'shutdown_forced');
+        state = 'exiting';
+        // The existing shutdownPromise will observe the state change and finalize.
+        return shutdownPromise ?? Promise.resolve();
+    }
+    // First signal: start draining.
+    state = 'draining';
+    shutdownStartedAt = Date.now();
+    log.info({ event: 'shutdown_start' }, 'shutdown_start');
+    const exitFn = opts.exit ?? ((code) => process.exit(code));
+    const timeoutMs = opts.shutdownTimeoutMs ?? Number(process.env.MAAD_SHUTDOWN_TIMEOUT_MS ?? DEFAULT_SHUTDOWN_TIMEOUT_MS);
+    shutdownPromise = (async () => {
+        let drainTimedOut = false;
+        const deadline = Date.now() + timeoutMs;
+        // Drain loop: wait until no writes are queued AND no requests are in flight
+        // OR the grace window expires, OR a second signal accelerates.
+        while (true) {
+            const queueDepth = target.pool.totalWriteQueueDepth();
+            const inFlight = target.rateLimiter.totalInFlight();
+            if (queueDepth === 0 && inFlight === 0)
+                break;
+            if (state === 'exiting')
+                break; // accelerated by a second signal
+            if (Date.now() >= deadline) {
+                drainTimedOut = true;
+                log.warn({
+                    event: 'shutdown_timeout',
+                    queue_depth: queueDepth,
+                    in_flight: inFlight,
+                    elapsed_ms: Date.now() - (shutdownStartedAt ?? Date.now()),
+                }, 'shutdown_timeout');
+                break;
+            }
+            await sleep(DRAIN_POLL_MS);
+        }
+        state = 'exiting';
+        // EXITING: final cleanup.
+        try {
+            await target.pool.closeAll();
+        }
+        catch {
+            // best-effort
+        }
+        if (opts.finalCleanup) {
+            try {
+                await opts.finalCleanup();
+            }
+            catch {
+                // best-effort
+            }
+        }
+        const elapsedMs = Date.now() - (shutdownStartedAt ?? Date.now());
+        log.info({
+            event: 'shutdown_complete',
+            elapsed_ms: elapsedMs,
+            drain_timed_out: drainTimedOut,
+        }, 'shutdown_complete');
+        // Exit code 1 on timed-out drain; 0 on clean drain. Surfaces to operators
+        // monitoring container exit codes.
+        exitFn(drainTimedOut ? 1 : 0);
+    })();
+    return shutdownPromise;
+}
+/**
+ * Install SIGTERM / SIGINT handlers that call beginShutdown on first hit and
+ * accelerate on the second. Call once from server startup. Tests bypass this
+ * by installing their own handlers or calling beginShutdown directly.
+ */
+export function installSignalHandlers(target, opts = {}) {
+    const onSignal = (sig) => {
+        const log = getOpsLog();
+        log.info({ event: 'signal_received', signal: sig }, 'signal_received');
+        void beginShutdown(target, opts);
+    };
+    process.on('SIGTERM', () => onSignal('SIGTERM'));
+    process.on('SIGINT', () => onSignal('SIGINT'));
+}
+function sleep(ms) {
+    return new Promise((r) => setTimeout(r, ms));
+}
+//# sourceMappingURL=shutdown.js.map

package/dist/mcp/shutdown.js.map

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

package/dist/mcp/tools/audit.d.ts

@@ -0,0 +1,4 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { InstanceCtx } from '../ctx.js';
+export declare function register(server: McpServer, ctx: InstanceCtx): number;
+//# sourceMappingURL=audit.d.ts.map

package/dist/mcp/tools/audit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"audit.d.ts","sourceRoot":"","sources":["../../../src/mcp/tools/audit.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAGzE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AAG7C,wBAAgB,QAAQ,CAAC,MAAM,EAAE,SAAS,EAAE,GAAG,EAAE,WAAW,GAAG,MAAM,CAiCpE"}

package/dist/mcp/tools/audit.js

@@ -0,0 +1,45 @@
+// ============================================================================
+// Audit tools — maad_history, maad_audit
+// ============================================================================
+import { z } from 'zod';
+import { docId, docType } from '../../types.js';
+import { resultToResponse } from '../response.js';
+import { withEngine } from '../with-session.js';
+export function register(server, ctx) {
+    server.registerTool('maad_history', {
+        description: 'Returns git commit history for a specific document.',
+        inputSchema: z.object({
+            docId: z.string().describe('Document ID'),
+            limit: z.number().optional().describe('Max commits to return'),
+            since: z.string().optional().describe('Only commits since this date (ISO or git date format)'),
+            project: z.string().optional().describe('Project name (multi-project mode only)'),
+        }),
+    }, async (args, extra) => withEngine(ctx, extra, 'maad_history', args, async ({ engine }) => {
+        const opts = {};
+        if (args.limit !== undefined)
+            opts.limit = args.limit;
+        if (args.since !== undefined)
+            opts.since = args.since;
+        return resultToResponse(await engine.history(docId(args.docId), opts));
+    }));
+    server.registerTool('maad_audit', {
+        description: 'Returns project-wide activity log from git. Shows most recent action per document.',
+        inputSchema: z.object({
+            since: z.string().optional().describe('Activity since date'),
+            until: z.string().optional().describe('Activity until date'),
+            docType: z.string().optional().describe('Filter by document type'),
+            project: z.string().optional().describe('Project name (multi-project mode only)'),
+        }),
+    }, async (args, extra) => withEngine(ctx, extra, 'maad_audit', args, async ({ engine }) => {
+        const opts = {};
+        if (args.since !== undefined)
+            opts.since = args.since;
+        if (args.until !== undefined)
+            opts.until = args.until;
+        if (args.docType !== undefined)
+            opts.docType = docType(args.docType);
+        return resultToResponse(await engine.audit(opts));
+    }));
+    return 2;
+}
+//# sourceMappingURL=audit.js.map

package/dist/mcp/tools/audit.js.map

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

package/dist/mcp/tools/auth.d.ts

@@ -0,0 +1,4 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { InstanceCtx } from '../ctx.js';
+export declare function register(server: McpServer, ctx: InstanceCtx): number;
+//# sourceMappingURL=auth.d.ts.map

package/dist/mcp/tools/auth.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth.d.ts","sourceRoot":"","sources":["../../../src/mcp/tools/auth.ts"],"names":[],"mappings":"AAeA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAGzE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AA4C7C,wBAAgB,QAAQ,CAAC,MAAM,EAAE,SAAS,EAAE,GAAG,EAAE,WAAW,GAAG,MAAM,CA0HpE"}