memory-journal-mcp 8.0.1 → 9.1.0

package/dist/utils/error-helpers.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Centralized Error Helpers for Memory Journal MCP
+ *
+ * Provides consistent error formatting across all tool handlers.
+ * All errors return structured responses instead of throwing
+ * uncaught exceptions.
+ */
+import { ZodError } from 'zod';
+import type { ErrorResponse } from '../types/error-types.js';
+/**
+ * Extract human-readable messages from a ZodError instead of raw JSON array.
+ * Maps each Zod issue to its path + message for clear validation feedback.
+ */
+export declare function formatZodError(error: ZodError): string;
+/**
+ * Format any caught error into an enriched ErrorResponse.
+ *
+ * Returns structured error information including code, category,
+ * suggestion, and recoverable flag. Handles MemoryJournalMcpError
+ * (full context), ZodError (validation), and raw errors (internal
+ * with pattern-matched suggestions from ERROR_SUGGESTIONS).
+ *
+ * Use as the single catch block for all tool handlers:
+ *
+ * ```typescript
+ * handler: async (params) => {
+ *   try {
+ *     const parsed = Schema.parse(params);
+ *     // ... domain logic ...
+ *     return { success: true, ... };
+ *   } catch (err) {
+ *     return formatHandlerError(err);
+ *   }
+ * }
+ * ```
+ */
+export declare function formatHandlerError(err: unknown): ErrorResponse;
+//# sourceMappingURL=error-helpers.d.ts.map

package/dist/utils/error-helpers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"error-helpers.d.ts","sourceRoot":"","sources":["../../src/utils/error-helpers.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,QAAQ,EAAE,MAAM,KAAK,CAAA;AAE9B,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAA;AAG5D;;;GAGG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,QAAQ,GAAG,MAAM,CAOtD;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,OAAO,GAAG,aAAa,CAqE9D"}

package/dist/utils/errors/error-response-fields.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Shared Error Response Fields for Output Schemas
+ *
+ * Defines the ErrorFieldsMixin Zod schema fragment that gets extended into
+ * every output schema. This ensures formatHandlerError() responses pass
+ * output schema validation (MCP SDK enforces additionalProperties: false).
+ *
+ * SSoT location: src/utils/errors/error-response-fields.ts
+ * All output schemas should import from here.
+ */
+import { z } from 'zod';
+/**
+ * Standard error response fields returned by formatHandlerError().
+ * Extend this into every output schema:
+ *   export const MyOutputSchema = z.object({ ... }).extend(ErrorFieldsMixin.shape);
+ */
+export declare const ErrorFieldsMixin: z.ZodObject<{
+    error: z.ZodOptional<z.ZodString>;
+    code: z.ZodOptional<z.ZodString>;
+    category: z.ZodOptional<z.ZodString>;
+    recoverable: z.ZodOptional<z.ZodBoolean>;
+    suggestion: z.ZodOptional<z.ZodString>;
+    aggregated_errors: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        message: z.ZodString;
+    }, z.core.$catchall<z.ZodUnknown>>>>;
+    details: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, z.core.$strip>;
+//# sourceMappingURL=error-response-fields.d.ts.map

package/dist/utils/errors/error-response-fields.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"error-response-fields.d.ts","sourceRoot":"","sources":["../../../src/utils/errors/error-response-fields.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AAEvB;;;;GAIG;AACH,eAAO,MAAM,gBAAgB;;;;;;;;;;iBAc3B,CAAA"}

package/dist/utils/errors/suggestions.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Error Suggestions — Fuzzy Pattern Matching for Error Messages
+ *
+ * Maps common error message patterns to actionable suggestions and
+ * specific error codes. Used by:
+ * 1. MemoryJournalMcpError constructor — auto-refines generic codes
+ * 2. formatHandlerError() — enriches raw Error responses
+ */
+interface ErrorSuggestion {
+    /** RegExp to test against error messages (case-insensitive) */
+    pattern: RegExp;
+    /** Human-readable suggestion for resolving the error */
+    suggestion: string;
+    /** Optional specific code to auto-refine generic codes into */
+    code?: string;
+}
+/** Codes that can be refined to a more specific code when a pattern matches */
+export declare const GENERIC_CODES: Set<string>;
+export declare const ERROR_SUGGESTIONS: ErrorSuggestion[];
+/**
+ * Find the first matching suggestion for an error message.
+ * Returns `undefined` if no pattern matches.
+ */
+export declare function matchSuggestion(message: string): {
+    suggestion: string;
+    code?: string | undefined;
+} | undefined;
+export {};
+//# sourceMappingURL=suggestions.d.ts.map

package/dist/utils/errors/suggestions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"suggestions.d.ts","sourceRoot":"","sources":["../../../src/utils/errors/suggestions.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAMH,UAAU,eAAe;IACrB,+DAA+D;IAC/D,OAAO,EAAE,MAAM,CAAA;IACf,wDAAwD;IACxD,UAAU,EAAE,MAAM,CAAA;IAClB,+DAA+D;IAC/D,IAAI,CAAC,EAAE,MAAM,CAAA;CAChB;AAMD,+EAA+E;AAC/E,eAAO,MAAM,aAAa,aAA+D,CAAA;AAMzF,eAAO,MAAM,iBAAiB,EAAE,eAAe,EAoG9C,CAAA;AAMD;;;GAGG;AACH,wBAAgB,eAAe,CAC3B,OAAO,EAAE,MAAM,GAChB;IAAE,UAAU,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;CAAE,GAAG,SAAS,CAO/D"}

package/dist/utils/github-helpers.d.ts

@@ -0,0 +1,12 @@
+import type { ToolContext } from '../types/index.js';
+/**
+ * Resolve a GitHub issue URL dynamically based on project context.
+ *
+ * If `existingUrl` is already provided, returns it unchanged.
+ * If `issueNumber` is provided, looks up the corresponding repository via
+ * project registry mappings or falls back to the globally cached repo info.
+ *
+ * @returns The resolved issue URL, or undefined if not resolvable
+ */
+export declare function resolveIssueUrl(context: ToolContext, projectNumber: number | undefined, issueNumber: number | undefined, existingUrl: string | undefined): Promise<string | undefined>;
+//# sourceMappingURL=github-helpers.d.ts.map

package/dist/utils/github-helpers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"github-helpers.d.ts","sourceRoot":"","sources":["../../src/utils/github-helpers.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAA;AAEpD;;;;;;;;GAQG;AACH,wBAAsB,eAAe,CACjC,OAAO,EAAE,WAAW,EACpB,aAAa,EAAE,MAAM,GAAG,SAAS,EACjC,WAAW,EAAE,MAAM,GAAG,SAAS,EAC/B,WAAW,EAAE,MAAM,GAAG,SAAS,GAChC,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAoC7B"}

package/dist/utils/issue-logger.d.ts

@@ -0,0 +1,10 @@
+export interface AgentIssue {
+    timestamp: string;
+    level: 'error' | 'warn' | 'info';
+    source: 'CLI' | 'MCP';
+    action: string;
+    input: unknown;
+    error: string;
+}
+export declare function logAgentIssue(issue: Omit<AgentIssue, 'timestamp' | 'level'>): void;
+//# sourceMappingURL=issue-logger.d.ts.map

package/dist/utils/issue-logger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"issue-logger.d.ts","sourceRoot":"","sources":["../../src/utils/issue-logger.ts"],"names":[],"mappings":"AAIA,MAAM,WAAW,UAAU;IACvB,SAAS,EAAE,MAAM,CAAA;IACjB,KAAK,EAAE,OAAO,GAAG,MAAM,GAAG,MAAM,CAAA;IAChC,MAAM,EAAE,KAAK,GAAG,KAAK,CAAA;IACrB,MAAM,EAAE,MAAM,CAAA;IACd,KAAK,EAAE,OAAO,CAAA;IACd,KAAK,EAAE,MAAM,CAAA;CAChB;AAiBD,wBAAgB,aAAa,CAAC,KAAK,EAAE,IAAI,CAAC,UAAU,EAAE,WAAW,GAAG,OAAO,CAAC,GAAG,IAAI,CA+BlF"}

package/dist/utils/logger.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Memory Journal MCP Server - Logger
+ *
+ * Centralized logging to stderr only (stdout reserved for MCP protocol).
+ * Follows RFC 5424 severity levels.
+ * Automatically sanitizes error fields to prevent token leakage.
+ */
+type LogLevel = 'debug' | 'info' | 'notice' | 'warning' | 'error' | 'critical';
+interface LogContext {
+    module?: string;
+    operation?: string;
+    entityId?: string | number;
+    [key: string]: unknown;
+}
+declare class Logger {
+    private minLevel;
+    constructor(level?: LogLevel);
+    private shouldLog;
+    private log;
+    debug(message: string, context?: LogContext): void;
+    info(message: string, context?: LogContext): void;
+    notice(message: string, context?: LogContext): void;
+    warning(message: string, context?: LogContext): void;
+    error(message: string, context?: LogContext): void;
+    critical(message: string, context?: LogContext): void;
+    setLevel(level: LogLevel): void;
+}
+export declare const logger: Logger;
+export {};
+//# sourceMappingURL=logger.d.ts.map

package/dist/utils/logger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../../src/utils/logger.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAIH,KAAK,QAAQ,GAAG,OAAO,GAAG,MAAM,GAAG,QAAQ,GAAG,SAAS,GAAG,OAAO,GAAG,UAAU,CAAA;AAE9E,UAAU,UAAU;IAChB,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,CAAA;IAC1B,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAA;CACzB;AAWD,cAAM,MAAM;IACR,OAAO,CAAC,QAAQ,CAAQ;gBAEZ,KAAK,GAAE,QAAiB;IAIpC,OAAO,CAAC,SAAS;IAIjB,OAAO,CAAC,GAAG;IAiCX,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,UAAU,GAAG,IAAI;IAIlD,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,UAAU,GAAG,IAAI;IAIjD,MAAM,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,UAAU,GAAG,IAAI;IAInD,OAAO,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,UAAU,GAAG,IAAI;IAIpD,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,UAAU,GAAG,IAAI;IAIlD,QAAQ,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,UAAU,GAAG,IAAI;IAIrD,QAAQ,CAAC,KAAK,EAAE,QAAQ,GAAG,IAAI;CAKlC;AAMD,eAAO,MAAM,MAAM,QAAuB,CAAA"}

package/dist/utils/maintenance-lock.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Server Runtime Context
+ *
+ * Provides instance-scoped globals (maintenance lock, tools cache, audit logger, etc.)
+ * to eliminate cross-instance process coupling.
+ */
+import type { AuditLogger, AuditInterceptor } from '../audit/index.js';
+import type { ToolRegistration, ToolDefinition } from '../types/index.js';
+import type { GitHubIntegration } from '../github/github-integration/index.js';
+import { MetricsAccumulator } from '../observability/metrics.js';
+export declare class MaintenanceManager {
+    private activeJobs;
+    private maintenanceWaitPromise;
+    private inMaintenanceMode;
+    withActiveJob<T>(fn: () => Promise<T>, bypass?: boolean): Promise<T>;
+    yieldJob(): void;
+    resumeJob(): void;
+    acquireMaintenanceLock(): Promise<void>;
+    releaseMaintenanceLock(): void;
+    assertNotInMaintenanceMode(): void;
+    isMaintenanceModeActive(): boolean;
+}
+export declare class ServerRuntime {
+    readonly maintenanceManager: MaintenanceManager;
+    readonly metrics: MetricsAccumulator;
+    auditLogger: AuditLogger | null;
+    auditInterceptor: AuditInterceptor | null;
+    toolMapCache: Map<string, ToolDefinition> | null;
+    mappedToolsCache: ToolRegistration[] | null;
+    cachedContextRefs: unknown;
+    githubClientPool: Map<string, GitHubIntegration> | null;
+    configManager: unknown;
+}
+//# sourceMappingURL=maintenance-lock.d.ts.map

package/dist/utils/maintenance-lock.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"maintenance-lock.d.ts","sourceRoot":"","sources":["../../src/utils/maintenance-lock.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,KAAK,EAAE,WAAW,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAA;AACtE,OAAO,KAAK,EAAE,gBAAgB,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAA;AACzE,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,uCAAuC,CAAA;AAC9E,OAAO,EAAE,kBAAkB,EAAE,MAAM,6BAA6B,CAAA;AAGhE,qBAAa,kBAAkB;IAC3B,OAAO,CAAC,UAAU,CAAI;IACtB,OAAO,CAAC,sBAAsB,CAA+D;IAC7F,OAAO,CAAC,iBAAiB,CAAQ;IAE3B,aAAa,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EAAE,MAAM,UAAQ,GAAG,OAAO,CAAC,CAAC,CAAC;IAyBxE,QAAQ,IAAI,IAAI;IAWhB,SAAS,IAAI,IAAI;IAIX,sBAAsB,IAAI,OAAO,CAAC,IAAI,CAAC;IAuB7C,sBAAsB,IAAI,IAAI;IAQ9B,0BAA0B,IAAI,IAAI;IAWlC,uBAAuB,IAAI,OAAO;CAGrC;AAED,qBAAa,aAAa;IACtB,SAAgB,kBAAkB,qBAA2B;IAC7D,SAAgB,OAAO,qBAA2B;IAC3C,WAAW,EAAE,WAAW,GAAG,IAAI,CAAO;IACtC,gBAAgB,EAAE,gBAAgB,GAAG,IAAI,CAAO;IAChD,YAAY,EAAE,GAAG,CAAC,MAAM,EAAE,cAAc,CAAC,GAAG,IAAI,CAAO;IACvD,gBAAgB,EAAE,gBAAgB,EAAE,GAAG,IAAI,CAAO;IAClD,iBAAiB,EAAE,OAAO,CAAO;IACjC,gBAAgB,EAAE,GAAG,CAAC,MAAM,EAAE,iBAAiB,CAAC,GAAG,IAAI,CAAO;IAC9D,aAAa,EAAE,OAAO,CAAO;CACvC"}

package/dist/utils/mcp-logger.d.ts

@@ -0,0 +1,73 @@
+/**
+ * Memory Journal MCP Server - MCP Protocol Logger
+ *
+ * Logging that sends structured messages via MCP notifications/message.
+ * Falls back to stderr when MCP server is not connected.
+ * Follows RFC 5424 severity levels as per MCP spec.
+ */
+import { type McpServer } from '@modelcontextprotocol/server';
+/**
+ * Narrow interface for MCP protocol log notification dispatch.
+ * Decouples McpLogger from the SDK's SEP-2577 deprecation annotation on McpServer
+ * while maintaining backward-compatible notifications/message support.
+ */
+export interface McpLoggingReceiver {
+    sendLoggingMessage(params: {
+        level: McpLogLevel;
+        logger?: string;
+        data: unknown;
+    }): Promise<void> | void;
+}
+/**
+ * MCP log levels per RFC 5424
+ */
+export type McpLogLevel = 'debug' | 'info' | 'notice' | 'warning' | 'error' | 'critical' | 'alert' | 'emergency';
+interface LogData {
+    message: string;
+    module?: string;
+    operation?: string;
+    [key: string]: unknown;
+}
+/**
+ * MCP Protocol Logger
+ *
+ * Sends structured log messages via MCP notifications/message protocol.
+ * Falls back to stderr when server not connected.
+ */
+export declare class McpLogger {
+    private server;
+    private minLevel;
+    /**
+     * Connect to MCP server for protocol logging
+     */
+    setServer(server: McpServer | McpLoggingReceiver): void;
+    /**
+     * Set minimum log level (from logging/setLevel request)
+     */
+    setLevel(level: McpLogLevel): void;
+    /**
+     * Get current minimum log level
+     */
+    getLevel(): McpLogLevel;
+    /**
+     * Check if a level should be logged
+     */
+    private shouldLog;
+    /**
+     * Format message for stderr fallback
+     */
+    private formatForStderr;
+    /**
+     * Send log message via MCP protocol or fallback to stderr
+     */
+    log(level: McpLogLevel, loggerName: string, data: LogData): void;
+    debug(loggerName: string, message: string, context?: Record<string, unknown>): void;
+    info(loggerName: string, message: string, context?: Record<string, unknown>): void;
+    notice(loggerName: string, message: string, context?: Record<string, unknown>): void;
+    warning(loggerName: string, message: string, context?: Record<string, unknown>): void;
+    error(loggerName: string, message: string, context?: Record<string, unknown>): void;
+    critical(loggerName: string, message: string, context?: Record<string, unknown>): void;
+}
+export declare const mcpLogger: McpLogger;
+export {};
+//# sourceMappingURL=mcp-logger.d.ts.map

package/dist/utils/mcp-logger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp-logger.d.ts","sourceRoot":"","sources":["../../src/utils/mcp-logger.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,KAAK,SAAS,EAAE,MAAM,8BAA8B,CAAA;AAE7D;;;;GAIG;AACH,MAAM,WAAW,kBAAkB;IAC/B,kBAAkB,CAAC,MAAM,EAAE;QACvB,KAAK,EAAE,WAAW,CAAA;QAClB,MAAM,CAAC,EAAE,MAAM,CAAA;QACf,IAAI,EAAE,OAAO,CAAA;KAChB,GAAG,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAA;CAC3B;AAED;;GAEG;AACH,MAAM,MAAM,WAAW,GACjB,OAAO,GACP,MAAM,GACN,QAAQ,GACR,SAAS,GACT,OAAO,GACP,UAAU,GACV,OAAO,GACP,WAAW,CAAA;AAajB,UAAU,OAAO;IACb,OAAO,EAAE,MAAM,CAAA;IACf,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAA;CACzB;AAED;;;;;GAKG;AACH,qBAAa,SAAS;IAClB,OAAO,CAAC,MAAM,CAAkC;IAChD,OAAO,CAAC,QAAQ,CAAsB;IAEtC;;OAEG;IACH,SAAS,CAAC,MAAM,EAAE,SAAS,GAAG,kBAAkB,GAAG,IAAI;IAIvD;;OAEG;IACH,QAAQ,CAAC,KAAK,EAAE,WAAW,GAAG,IAAI;IAMlC;;OAEG;IACH,QAAQ,IAAI,WAAW;IAIvB;;OAEG;IACH,OAAO,CAAC,SAAS;IAIjB;;OAEG;IACH,OAAO,CAAC,eAAe;IAmBvB;;OAEG;IACH,GAAG,CAAC,KAAK,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,GAAG,IAAI;IAsBhE,KAAK,CAAC,UAAU,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI;IAInF,IAAI,CAAC,UAAU,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI;IAIlF,MAAM,CAAC,UAAU,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI;IAIpF,OAAO,CAAC,UAAU,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI;IAIrF,KAAK,CAAC,UAAU,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI;IAInF,QAAQ,CAAC,UAAU,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI;CAGzF;AAGD,eAAO,MAAM,SAAS,WAAkB,CAAA"}

package/dist/utils/progress-utils.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Memory Journal MCP Server - Progress Notification Utilities
+ *
+ * Utilities for sending MCP progress notifications during long-running operations.
+ * Follows MCP 2025-11-25 specification for notifications/progress.
+ */
+/**
+ * Minimal interface for sending MCP notifications.
+ * Uses structural typing to avoid importing the deprecated Server class.
+ */
+interface NotificationSender {
+    notification(notification: {
+        method: 'notifications/progress';
+        params: {
+            progressToken: string | number;
+            progress: number;
+            total?: number;
+            message?: string;
+        };
+    }): Promise<void>;
+}
+/** Progress token from client request _meta */
+export type ProgressToken = string | number;
+/** Context required to send progress notifications */
+export interface ProgressContext {
+    /** Object with notification method for sending progress updates */
+    server: NotificationSender;
+    /** Progress token from request _meta (if client requested progress) */
+    progressToken?: ProgressToken;
+}
+/**
+ * Send a progress notification to the client.
+ *
+ * Only sends if a progressToken was provided in the original request.
+ * Silently no-ops if no token was provided.
+ *
+ * @param ctx - Progress context with server and optional token
+ * @param progress - Current progress value (e.g., items processed)
+ * @param total - Optional total value for percentage calculation
+ * @param message - Optional human-readable status message
+ */
+export declare function sendProgress(ctx: ProgressContext | undefined, progress: number, total?: number, message?: string): Promise<void>;
+/**
+ * Create a progress reporter function for batch operations.
+ *
+ * @param ctx - Progress context
+ * @param total - Total number of items to process
+ * @param throttle - Report every N items (default: 10)
+ * @returns Async function to call on each item processed
+ */
+export declare function createBatchProgressReporter(ctx: ProgressContext | undefined, total: number, throttle?: number): (current: number, message?: string) => Promise<void>;
+export {};
+//# sourceMappingURL=progress-utils.d.ts.map

package/dist/utils/progress-utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"progress-utils.d.ts","sourceRoot":"","sources":["../../src/utils/progress-utils.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH;;;GAGG;AACH,UAAU,kBAAkB;IACxB,YAAY,CAAC,YAAY,EAAE;QACvB,MAAM,EAAE,wBAAwB,CAAA;QAChC,MAAM,EAAE;YACJ,aAAa,EAAE,MAAM,GAAG,MAAM,CAAA;YAC9B,QAAQ,EAAE,MAAM,CAAA;YAChB,KAAK,CAAC,EAAE,MAAM,CAAA;YACd,OAAO,CAAC,EAAE,MAAM,CAAA;SACnB,CAAA;KACJ,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;CACpB;AAED,+CAA+C;AAC/C,MAAM,MAAM,aAAa,GAAG,MAAM,GAAG,MAAM,CAAA;AAE3C,sDAAsD;AACtD,MAAM,WAAW,eAAe;IAC5B,mEAAmE;IACnE,MAAM,EAAE,kBAAkB,CAAA;IAC1B,uEAAuE;IACvE,aAAa,CAAC,EAAE,aAAa,CAAA;CAChC;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,YAAY,CAC9B,GAAG,EAAE,eAAe,GAAG,SAAS,EAChC,QAAQ,EAAE,MAAM,EAChB,KAAK,CAAC,EAAE,MAAM,EACd,OAAO,CAAC,EAAE,MAAM,GACjB,OAAO,CAAC,IAAI,CAAC,CAyBf;AAED;;;;;;;GAOG;AACH,wBAAgB,2BAA2B,CACvC,GAAG,EAAE,eAAe,GAAG,SAAS,EAChC,KAAK,EAAE,MAAM,EACb,QAAQ,SAAK,GACd,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAUtD"}

package/dist/utils/query-helpers.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Query Helpers — Input Coercion Utilities
+ *
+ * Standard coercion helpers that safely convert MCP SDK inputs (which may
+ * arrive as strings due to JSON serialization) into their expected types.
+ *
+ * Used with `z.preprocess()` to ensure bad input reaches the handler's
+ * try/catch instead of causing raw -32602 protocol errors.
+ */
+/** Default number of rows returned by query tools */
+export declare const DEFAULT_QUERY_LIMIT = 100;
+/**
+ * Coerce a value to a number. Returns `undefined` for non-numeric input
+ * so Zod treats it as "not provided" instead of producing NaN.
+ *
+ * Usage: `z.preprocess(coerceNumber, z.number().optional())`
+ */
+export declare function coerceNumber(val: unknown): unknown;
+/**
+ * Coerce a value to a boolean. Handles string "true"/"false" from
+ * MCP SDK serialization.
+ *
+ * Usage: `z.preprocess(coerceBoolean, z.boolean().optional())`
+ */
+export declare function coerceBoolean(val: unknown): unknown;
+/**
+ * Coerce a raw limit value to a usable number.
+ * - `undefined` → `defaultLimit`
+ * - `NaN` → `defaultLimit`
+ * - `0` → `null` (meaning "unlimited")
+ * - negative → `defaultLimit`
+ * - positive → the value itself
+ *
+ * Works with both `z.preprocess(coerceNumber, ...)` and `z.coerce.number()`
+ * outputs, safely handling NaN and undefined.
+ */
+export declare function coerceLimit(raw: unknown, defaultLimit?: number): number | null;
+/**
+ * Build a SQL LIMIT clause from a coerced limit value.
+ * `null` means "no limit" — returns an empty string.
+ */
+export declare function buildLimitClause(limitVal: number | null): string;
+//# sourceMappingURL=query-helpers.d.ts.map

package/dist/utils/query-helpers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"query-helpers.d.ts","sourceRoot":"","sources":["../../src/utils/query-helpers.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAMH,qDAAqD;AACrD,eAAO,MAAM,mBAAmB,MAAM,CAAA;AAMtC;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAOlD;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAKnD;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,WAAW,CACvB,GAAG,EAAE,OAAO,EACZ,YAAY,GAAE,MAA4B,GAC3C,MAAM,GAAG,IAAI,CAMf;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,GAAG,MAAM,CAEhE"}

package/dist/utils/request-context.d.ts

@@ -0,0 +1,9 @@
+import { AsyncLocalStorage } from 'node:async_hooks';
+export interface RequestContext {
+    ip?: string | undefined;
+    sessionId?: string | undefined;
+    useTestDb?: boolean | undefined;
+}
+export declare const requestContextStorage: AsyncLocalStorage<RequestContext>;
+export declare function getRequestContext(): RequestContext | undefined;
+//# sourceMappingURL=request-context.d.ts.map

package/dist/utils/request-context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"request-context.d.ts","sourceRoot":"","sources":["../../src/utils/request-context.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAA;AAEpD,MAAM,WAAW,cAAc;IAC3B,EAAE,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IACvB,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IAC9B,SAAS,CAAC,EAAE,OAAO,GAAG,SAAS,CAAA;CAClC;AAED,eAAO,MAAM,qBAAqB,mCAA0C,CAAA;AAE5E,wBAAgB,iBAAiB,IAAI,cAAc,GAAG,SAAS,CAE9D"}

package/dist/utils/resource-annotations.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Resource Annotation Presets
+ *
+ * Centralized annotation presets for MCP resources following
+ * MCP 2025-11-25 spec. Use these instead of inline annotation
+ * objects to ensure consistency across all resource definitions.
+ */
+interface ResourceAnnotation {
+    audience?: ('user' | 'assistant')[];
+    priority?: number;
+    autoRead?: boolean;
+    sessionInit?: boolean;
+}
+/** Critical state resources (health, schema, activity) — priority 0.9 */
+export declare const HIGH_PRIORITY: ResourceAnnotation;
+/** Analysis/monitoring resources (stats, indexes) — priority 0.6 */
+export declare const MEDIUM_PRIORITY: ResourceAnnotation;
+/** Supplementary resources (pool stats, extension status) — priority 0.4 */
+export declare const LOW_PRIORITY: ResourceAnnotation;
+/** Agent-only resources (capabilities, settings, instructions) — priority 0.5 */
+export declare const ASSISTANT_FOCUSED: ResourceAnnotation;
+/**
+ * Create a custom-priority annotation, optionally extending a base preset.
+ */
+export declare function withPriority(priority: number, base?: ResourceAnnotation): ResourceAnnotation;
+/**
+ * Clone a base annotation with autoRead flag set.
+ * Useful for session-init resources that should be auto-read.
+ */
+export declare function withAutoRead(base?: ResourceAnnotation): ResourceAnnotation;
+/**
+ * Clone a base annotation with sessionInit flag set.
+ */
+export declare function withSessionInit(base?: ResourceAnnotation): ResourceAnnotation;
+export {};
+//# sourceMappingURL=resource-annotations.d.ts.map

package/dist/utils/resource-annotations.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resource-annotations.d.ts","sourceRoot":"","sources":["../../src/utils/resource-annotations.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAMH,UAAU,kBAAkB;IACxB,QAAQ,CAAC,EAAE,CAAC,MAAM,GAAG,WAAW,CAAC,EAAE,CAAA;IACnC,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,QAAQ,CAAC,EAAE,OAAO,CAAA;IAClB,WAAW,CAAC,EAAE,OAAO,CAAA;CACxB;AAMD,yEAAyE;AACzE,eAAO,MAAM,aAAa,EAAE,kBAG3B,CAAA;AAED,oEAAoE;AACpE,eAAO,MAAM,eAAe,EAAE,kBAG7B,CAAA;AAED,4EAA4E;AAC5E,eAAO,MAAM,YAAY,EAAE,kBAG1B,CAAA;AAED,iFAAiF;AACjF,eAAO,MAAM,iBAAiB,EAAE,kBAG/B,CAAA;AAMD;;GAEG;AACH,wBAAgB,YAAY,CACxB,QAAQ,EAAE,MAAM,EAChB,IAAI,GAAE,kBAAoC,GAC3C,kBAAkB,CAEpB;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAAC,IAAI,GAAE,kBAAkC,GAAG,kBAAkB,CAEzF;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,IAAI,GAAE,kBAAkC,GAAG,kBAAkB,CAE5F"}

package/dist/utils/security-utils.d.ts

@@ -0,0 +1,113 @@
+import { MemoryJournalMcpError } from '../types/errors.js';
+/**
+ * Base class for security-related errors.
+ * Extends MemoryJournalMcpError with VALIDATION category.
+ */
+export declare class SecurityError extends MemoryJournalMcpError {
+    constructor(message: string, code: string);
+}
+/**
+ * Thrown when an invalid date format pattern is detected
+ */
+export declare class InvalidDateFormatError extends SecurityError {
+    constructor(value: string);
+}
+/**
+ * Thrown when path traversal is detected in input
+ */
+export declare class PathTraversalError extends SecurityError {
+    constructor(path: string);
+}
+export type DateGroupBy = 'day' | 'week' | 'month';
+/**
+ * Validates and returns a safe strftime format pattern.
+ *
+ * @param groupBy - The grouping period ('day', 'week', or 'month')
+ * @returns The validated strftime format pattern
+ * @throws InvalidDateFormatError if the groupBy value is invalid
+ *
+ * @example
+ * ```typescript
+ * const format = validateDateFormatPattern('day') // Returns '%Y-%m-%d'
+ * const format = validateDateFormatPattern('invalid') // Throws InvalidDateFormatError
+ * ```
+ */
+export declare function validateDateFormatPattern(groupBy: string): string;
+/**
+ * Escapes special characters in LIKE patterns to prevent injection.
+ * SQLite LIKE uses % and _ as wildcards.
+ *
+ * @param query - The user-provided search query
+ * @returns Escaped query safe for use in LIKE patterns
+ *
+ * @example
+ * ```typescript
+ * sanitizeSearchQuery('100%') // Returns '100\\%'
+ * sanitizeSearchQuery('test_value') // Returns 'test\\_value'
+ * ```
+ */
+export declare function sanitizeSearchQuery(query: string): string;
+/**
+ * Validates that a filename does not contain path traversal characters.
+ *
+ * @param filename - The filename to validate
+ * @throws PathTraversalError if path traversal is detected
+ */
+export declare function assertNoPathTraversal(filename: string): void;
+/**
+ * Validates that a directory path is strictly bounded within the active memory journal context.
+ *
+ * This enforces strict file-system isolation. The target path MUST reside within:
+ * 1. The current working directory (where the server was started)
+ * 2. OR any explicitly configured path inside the PROJECT_REGISTRY map.
+ *
+ * @param dirPath - The directory path to validate
+ * @throws PathTraversalError if the path escapes the sandboxed boundaries
+ */
+export declare function assertSafeDirectoryPath(dirPath: string, providedRoots: string[]): void;
+/**
+ * Validates that a file path is strictly bounded and refuses symlinks to prevent
+ * any file-level traversal tricks.
+ */
+export declare function assertSafeFilePath(filePath: string, providedRoots: string[]): void;
+/**
+ * Sanitizes an error message by replacing any detected tokens with '[REDACTED]'.
+ * This is a defense-in-depth measure for error logging paths.
+ *
+ * @param message - The error message to sanitize
+ * @returns The sanitized message with tokens replaced
+ */
+export declare function sanitizeErrorForLogging(message: string): string;
+/**
+ * Marks free-text content as untrusted remote origin for LLM instruction consumption.
+ * Defends against prompt-injection by surrounding external inputs with tags.
+ *
+ * Will not insert nested tags if the content is already marked.
+ */
+export declare function markUntrustedContent(content: string | undefined | null): string;
+/**
+ * Utility for formatting remote content natively for inline single-line contexts.
+ */
+export declare function markUntrustedContentInline(content: string | undefined | null): string;
+/**
+ * Sanitize an author string: strip control characters and cap length.
+ * Prevents crafted git config or TEAM_AUTHOR values from injecting
+ * control characters into the database or JSON payloads.
+ *
+ * @param raw - The raw author string from git config or environment
+ * @returns Sanitized string with control characters removed and length capped at 100
+ */
+export declare function sanitizeAuthor(raw: string): string;
+/**
+ * Resolve the author name strictly from the authenticated context.
+ * Prioritizes authenticated claims over TEAM_AUTHOR environment variables.
+ * Uses sanitizeAuthor() to strip control characters and cap length.
+ */
+export declare function resolveAuthenticatedAuthor(): string;
+/**
+ * Resolve the author name for team-shared entries.
+ * Priority: TEAM_AUTHOR env → req.auth.sub → 'unknown'.
+ * Uses sanitizeAuthor() to strip control characters and cap length.
+ */
+export declare function resolveAuthor(): string;
+//# sourceMappingURL=security-utils.d.ts.map

package/dist/utils/security-utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"security-utils.d.ts","sourceRoot":"","sources":["../../src/utils/security-utils.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,qBAAqB,EAAE,MAAM,oBAAoB,CAAA;AAM1D;;;GAGG;AACH,qBAAa,aAAc,SAAQ,qBAAqB;gBACxC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM;CAO5C;AAED;;GAEG;AACH,qBAAa,sBAAuB,SAAQ,aAAa;gBACzC,KAAK,EAAE,MAAM;CAI5B;AAED;;GAEG;AACH,qBAAa,kBAAmB,SAAQ,aAAa;gBACrC,IAAI,EAAE,MAAM;CAI3B;AAgBD,MAAM,MAAM,WAAW,GAAG,KAAK,GAAG,MAAM,GAAG,OAAO,CAAA;AAElD;;;;;;;;;;;;GAYG;AACH,wBAAgB,yBAAyB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CASjE;AAMD;;;;;;;;;;;;GAYG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAGzD;AAMD;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAI5D;AAKD;;;;;;;;;GASG;AACH,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,EAAE,GAAG,IAAI,CA4EtF;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,EAAE,GAAG,IAAI,CAkBlF;AA2BD;;;;;;GAMG;AACH,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAQ/D;AAMD;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,GAAG,MAAM,CAc/E;AAED;;GAEG;AACH,wBAAgB,0BAA0B,CAAC,OAAO,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,GAAG,MAAM,CAarF;AAMD;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAElD;AAMD;;;;GAIG;AACH,wBAAgB,0BAA0B,IAAI,MAAM,CAkBnD;AAED;;;;GAIG;AACH,wBAAgB,aAAa,IAAI,MAAM,CAoBtC"}

package/dist/utils/vector-index-helpers.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Vector Index Helpers
+ *
+ * Shared vector indexing logic used by entry-creation
+ * handlers (create_entry, create_entry_minimal, restore_entry, etc.).
+ */
+import type { VectorSearchManager } from '../vector/vector-search-manager/index.js';
+import type { IDatabaseAdapter } from '../database/core/interfaces.js';
+/**
+ * Auto-index an entry to the vector store for semantic search.
+ * Catch errors so as not to revert the database commit, but surface the state.
+ */
+export declare function autoIndexEntry(vectorManager: VectorSearchManager | undefined, db: IDatabaseAdapter, entryId: number, workspaceId?: string): Promise<'success' | 'failed' | 'disabled'>;
+//# sourceMappingURL=vector-index-helpers.d.ts.map

package/dist/utils/vector-index-helpers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"vector-index-helpers.d.ts","sourceRoot":"","sources":["../../src/utils/vector-index-helpers.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,0CAA0C,CAAA;AACnF,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,gCAAgC,CAAA;AAGtE;;;GAGG;AACH,wBAAsB,cAAc,CAChC,aAAa,EAAE,mBAAmB,GAAG,SAAS,EAC9C,EAAE,EAAE,gBAAgB,EACpB,OAAO,EAAE,MAAM,EACf,WAAW,CAAC,EAAE,MAAM,GACrB,OAAO,CAAC,SAAS,GAAG,QAAQ,GAAG,UAAU,CAAC,CAe5C"}

package/dist/utils/workspace-resolver.d.ts

@@ -0,0 +1,40 @@
+import type { ToolHandlerConfig } from '../types/index.js';
+export interface ResolutionInput {
+    workspace_id?: string;
+    project_number?: number;
+    content?: string;
+    tags?: string[];
+}
+export interface ResolvedContext {
+    workspaceId: string;
+    projectNumber: number | undefined;
+}
+export declare function loadProjectRegistryFromConfig(): Record<string, RegistryEntry> | undefined;
+export declare const PROJECT_KEYWORD_ALIASES: Record<string, string[]>;
+/**
+ * Resolves full workspace and project context from available inputs.
+ * Priority:
+ * 1. Explicit workspace_id (if not 'default') and explicit project_number
+ * 2. Explicit project_number -> lookup workspace_id in projectRegistry
+ * 3. Explicit workspace_id -> lookup project_number in projectRegistry
+ * 4. Content / Tags fuzzy matching against projectRegistry keys and names
+ * 5. process.cwd() path matching against projectRegistry
+ * 6. Config defaults or fallback 'default'
+ */
+export declare function resolveProjectContext(input: ResolutionInput, config?: ToolHandlerConfig): ResolvedContext;
+/**
+ * Resolves the effective workspace ID from available context.
+ * Priority: explicit workspace_id > project_number lookup > content/tags lookup > config default > 'default'
+ */
+export declare function resolveWorkspaceId(explicitWorkspaceId: string | undefined, projectNumber: number | undefined, config?: ToolHandlerConfig, content?: string, tags?: string[]): string;
+interface RegistryEntry {
+    path?: string;
+    project_number?: number;
+}
+/**
+ * Automatically resolves a project number by inspecting the global config
+ * and matching the provided working directory against registered paths.
+ */
+export declare function resolveProjectNumberFromPath(cwd: string): number | undefined;
+export {};
+//# sourceMappingURL=workspace-resolver.d.ts.map

package/dist/utils/workspace-resolver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"workspace-resolver.d.ts","sourceRoot":"","sources":["../../src/utils/workspace-resolver.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAA;AAK1D,MAAM,WAAW,eAAe;IAC5B,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,cAAc,CAAC,EAAE,MAAM,CAAA;IACvB,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,IAAI,CAAC,EAAE,MAAM,EAAE,CAAA;CAClB;AAED,MAAM,WAAW,eAAe;IAC5B,WAAW,EAAE,MAAM,CAAA;IACnB,aAAa,EAAE,MAAM,GAAG,SAAS,CAAA;CACpC;AASD,wBAAgB,6BAA6B,IAAI,MAAM,CAAC,MAAM,EAAE,aAAa,CAAC,GAAG,SAAS,CAazF;AAED,eAAO,MAAM,uBAAuB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAc5D,CAAA;AAuCD;;;;;;;;;GASG;AACH,wBAAgB,qBAAqB,CACjC,KAAK,EAAE,eAAe,EACtB,MAAM,CAAC,EAAE,iBAAiB,GAC3B,eAAe,CA8IjB;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAC9B,mBAAmB,EAAE,MAAM,GAAG,SAAS,EACvC,aAAa,EAAE,MAAM,GAAG,SAAS,EACjC,MAAM,CAAC,EAAE,iBAAiB,EAC1B,OAAO,CAAC,EAAE,MAAM,EAChB,IAAI,CAAC,EAAE,MAAM,EAAE,GAChB,MAAM,CAcR;AAED,UAAU,aAAa;IACnB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,cAAc,CAAC,EAAE,MAAM,CAAC;CAC3B;AAMD;;;GAGG;AACH,wBAAgB,4BAA4B,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAsC5E"}