ocr-provenance-mcp 1.0.0

package/dist/server/permissions.js

@@ -0,0 +1,194 @@
+/**
+ * Tool-Level Permission System
+ *
+ * 6 permission scopes, 4 roles.
+ * Each tool declares a required scope.
+ * Permission check runs before handler execution.
+ *
+ * FAIL FAST: Unauthorized access throws immediately.
+ *
+ * CRITICAL: NEVER use console.log() - stdout is reserved for JSON-RPC protocol.
+ *
+ * @module server/permissions
+ */
+// ═══════════════════════════════════════════════════════════════════════════════
+// ROLE-SCOPE MAPPING
+// ═══════════════════════════════════════════════════════════════════════════════
+/** Role to scopes mapping */
+const ROLE_SCOPES = {
+    viewer: new Set(['ocr:read']),
+    reviewer: new Set(['ocr:read', 'ocr:review']),
+    editor: new Set(['ocr:read', 'ocr:write', 'ocr:review']),
+    admin: new Set([
+        'ocr:read',
+        'ocr:write',
+        'ocr:review',
+        'ocr:configure',
+        'ocr:delete',
+        'ocr:admin',
+    ]),
+};
+// ═══════════════════════════════════════════════════════════════════════════════
+// PERMISSION CHECKS
+// ═══════════════════════════════════════════════════════════════════════════════
+/** Check if a role has a specific permission scope */
+export function hasPermission(role, scope) {
+    return ROLE_SCOPES[role]?.has(scope) ?? false;
+}
+/** Get all scopes for a role */
+export function getScopesForRole(role) {
+    return Array.from(ROLE_SCOPES[role] ?? []);
+}
+/** Validate that a role string is valid */
+export function isValidRole(role) {
+    return role in ROLE_SCOPES;
+}
+// ═══════════════════════════════════════════════════════════════════════════════
+// TOOL-SCOPE MAPPING
+// ═══════════════════════════════════════════════════════════════════════════════
+/** Tool name to required scope mapping */
+export const TOOL_SCOPES = {
+    // ── Read tools ────────────────────────────────────────────────────────────
+    ocr_db_list: 'ocr:read',
+    ocr_db_stats: 'ocr:read',
+    ocr_search: 'ocr:read',
+    ocr_fts_manage: 'ocr:read',
+    ocr_search_export: 'ocr:read',
+    ocr_benchmark_compare: 'ocr:read',
+    ocr_rag_context: 'ocr:read',
+    ocr_search_saved: 'ocr:read',
+    ocr_search_cross_db: 'ocr:read',
+    ocr_document_list: 'ocr:read',
+    ocr_document_get: 'ocr:read',
+    ocr_document_find_similar: 'ocr:read',
+    ocr_document_structure: 'ocr:read',
+    ocr_document_duplicates: 'ocr:read',
+    ocr_document_versions: 'ocr:read',
+    ocr_document_page: 'ocr:read',
+    ocr_export: 'ocr:read',
+    ocr_provenance_get: 'ocr:read',
+    ocr_provenance_verify: 'ocr:read',
+    ocr_provenance_export: 'ocr:read',
+    ocr_provenance_query: 'ocr:read',
+    ocr_provenance_timeline: 'ocr:read',
+    ocr_provenance_processor_stats: 'ocr:read',
+    ocr_vlm_status: 'ocr:read',
+    ocr_image_list: 'ocr:read',
+    ocr_image_get: 'ocr:read',
+    ocr_image_stats: 'ocr:read',
+    ocr_image_pending: 'ocr:read',
+    ocr_image_search: 'ocr:read',
+    ocr_chunk_get: 'ocr:read',
+    ocr_chunk_list: 'ocr:read',
+    ocr_chunk_context: 'ocr:read',
+    ocr_embedding_list: 'ocr:read',
+    ocr_embedding_stats: 'ocr:read',
+    ocr_embedding_get: 'ocr:read',
+    ocr_tag_list: 'ocr:read',
+    ocr_tag_search: 'ocr:read',
+    ocr_document_tables: 'ocr:read',
+    ocr_document_recommend: 'ocr:read',
+    ocr_document_extras: 'ocr:read',
+    ocr_table_export: 'ocr:read',
+    ocr_config_get: 'ocr:read',
+    ocr_health_check: 'ocr:read',
+    ocr_guide: 'ocr:read',
+    ocr_report_overview: 'ocr:read',
+    ocr_report_performance: 'ocr:read',
+    ocr_document_report: 'ocr:read',
+    ocr_evaluation_report: 'ocr:read',
+    ocr_error_analytics: 'ocr:read',
+    ocr_trends: 'ocr:read',
+    ocr_cost_summary: 'ocr:read',
+    ocr_status: 'ocr:read',
+    ocr_comparison_list: 'ocr:read',
+    ocr_comparison_get: 'ocr:read',
+    ocr_cluster_list: 'ocr:read',
+    ocr_cluster_get: 'ocr:read',
+    ocr_extraction_list: 'ocr:read',
+    ocr_extraction_get: 'ocr:read',
+    ocr_file_list: 'ocr:read',
+    ocr_file_get: 'ocr:read',
+    ocr_form_fill_status: 'ocr:read',
+    // ── Write tools ───────────────────────────────────────────────────────────
+    ocr_db_create: 'ocr:write',
+    ocr_db_select: 'ocr:write',
+    ocr_ingest_files: 'ocr:write',
+    ocr_ingest_directory: 'ocr:write',
+    ocr_process_pending: 'ocr:write',
+    ocr_reprocess: 'ocr:write',
+    ocr_retry_failed: 'ocr:write',
+    ocr_convert_raw: 'ocr:write',
+    ocr_embedding_rebuild: 'ocr:write',
+    ocr_vlm_describe: 'ocr:write',
+    ocr_vlm_process: 'ocr:write',
+    ocr_vlm_analyze_pdf: 'ocr:write',
+    ocr_extract_images: 'ocr:write',
+    ocr_extract_structured: 'ocr:write',
+    ocr_form_fill: 'ocr:write',
+    ocr_file_upload: 'ocr:write',
+    ocr_file_download: 'ocr:write',
+    ocr_file_ingest_uploaded: 'ocr:write',
+    ocr_document_compare: 'ocr:write',
+    ocr_comparison_discover: 'ocr:write',
+    ocr_comparison_batch: 'ocr:write',
+    ocr_comparison_matrix: 'ocr:write',
+    ocr_cluster_documents: 'ocr:write',
+    ocr_cluster_assign: 'ocr:write',
+    ocr_cluster_merge: 'ocr:write',
+    ocr_cluster_reassign: 'ocr:write',
+    ocr_tag_create: 'ocr:write',
+    ocr_tag_apply: 'ocr:write',
+    ocr_tag_remove: 'ocr:write',
+    ocr_document_update_metadata: 'ocr:write',
+    ocr_image_reanalyze: 'ocr:write',
+    ocr_image_reset_failed: 'ocr:write',
+    ocr_evaluate: 'ocr:write',
+    // ── Review tools (future Phase 2/3) ───────────────────────────────────────
+    ocr_document_workflow: 'ocr:review',
+    ocr_annotation_create: 'ocr:review',
+    ocr_annotation_update: 'ocr:review',
+    ocr_annotation_list: 'ocr:read',
+    ocr_annotation_get: 'ocr:read',
+    ocr_annotation_summary: 'ocr:read',
+    ocr_workflow_submit: 'ocr:review',
+    ocr_workflow_review: 'ocr:review',
+    ocr_workflow_assign: 'ocr:review',
+    ocr_workflow_status: 'ocr:read',
+    ocr_workflow_queue: 'ocr:read',
+    // ── Configure tools ───────────────────────────────────────────────────────
+    ocr_config_set: 'ocr:configure',
+    // ── Delete tools ──────────────────────────────────────────────────────────
+    ocr_document_delete: 'ocr:delete',
+    ocr_db_delete: 'ocr:delete',
+    ocr_tag_delete: 'ocr:delete',
+    ocr_cluster_delete: 'ocr:delete',
+    ocr_image_delete: 'ocr:delete',
+    ocr_file_delete: 'ocr:delete',
+    ocr_annotation_delete: 'ocr:delete',
+    ocr_document_unlock: 'ocr:delete',
+    // ── Admin tools ───────────────────────────────────────────────────────────
+    ocr_user_info: 'ocr:admin',
+    ocr_audit_query: 'ocr:admin',
+    ocr_webhook_create: 'ocr:admin',
+    ocr_webhook_list: 'ocr:admin',
+    ocr_webhook_delete: 'ocr:admin',
+    ocr_compliance_report: 'ocr:admin',
+    ocr_compliance_hipaa: 'ocr:admin',
+    ocr_compliance_export: 'ocr:admin',
+};
+// ═══════════════════════════════════════════════════════════════════════════════
+// PERMISSION CHECK
+// ═══════════════════════════════════════════════════════════════════════════════
+/** Check permission - returns true if allowed, false if denied. Admin always passes. */
+export function checkToolPermission(toolName, userRole) {
+    // No user context = local mode = full access
+    if (userRole === null)
+        return true;
+    const requiredScope = TOOL_SCOPES[toolName];
+    // Tools not in the map are allowed (new tools default to accessible)
+    if (!requiredScope)
+        return true;
+    return hasPermission(userRole, requiredScope);
+}
+//# sourceMappingURL=permissions.js.map

package/dist/server/permissions.js.map

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

package/dist/server/register-tools.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Shared Tool Registration
+ *
+ * Registers all MCP tools on a given McpServer instance.
+ * Used by both src/index.ts (stdio) and src/bin-http.ts (unified Docker entry).
+ *
+ * CRITICAL: NEVER use console.log() - stdout may be reserved for JSON-RPC protocol.
+ *
+ * @module server/register-tools
+ */
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+/**
+ * Register all tools on the given MCP server instance.
+ *
+ * @param server - McpServer instance to register tools on
+ * @returns Number of tools registered
+ * @throws Exits process with code 1 if duplicate tool names are detected
+ */
+export declare function registerAllTools(server: McpServer): number;
+/**
+ * Get total tool count without registering on a server instance.
+ * Used by HTTP mode health endpoint to avoid creating a throwaway McpServer.
+ */
+export declare function getToolCount(): number;
+//# sourceMappingURL=register-tools.d.ts.map

package/dist/server/register-tools.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"register-tools.d.ts","sourceRoot":"","sources":["../../src/server/register-tools.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AA8DzE;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,SAAS,GAAG,MAAM,CAmB1D;AAED;;;GAGG;AACH,wBAAgB,YAAY,IAAI,MAAM,CAMrC"}

package/dist/server/register-tools.js

@@ -0,0 +1,102 @@
+/**
+ * Shared Tool Registration
+ *
+ * Registers all MCP tools on a given McpServer instance.
+ * Used by both src/index.ts (stdio) and src/bin-http.ts (unified Docker entry).
+ *
+ * CRITICAL: NEVER use console.log() - stdout may be reserved for JSON-RPC protocol.
+ *
+ * @module server/register-tools
+ */
+import { databaseTools } from '../tools/database.js';
+import { ingestionTools } from '../tools/ingestion.js';
+import { searchTools } from '../tools/search.js';
+import { documentTools } from '../tools/documents.js';
+import { provenanceTools } from '../tools/provenance.js';
+import { configTools } from '../tools/config.js';
+import { vlmTools } from '../tools/vlm.js';
+import { imageTools } from '../tools/images.js';
+import { evaluationTools } from '../tools/evaluation.js';
+import { extractionTools } from '../tools/extraction.js';
+import { reportTools } from '../tools/reports.js';
+import { formFillTools } from '../tools/form-fill.js';
+import { structuredExtractionTools } from '../tools/extraction-structured.js';
+import { fileManagementTools } from '../tools/file-management.js';
+import { comparisonTools } from '../tools/comparison.js';
+import { clusteringTools } from '../tools/clustering.js';
+import { chunkTools } from '../tools/chunks.js';
+import { embeddingTools } from '../tools/embeddings.js';
+import { tagTools } from '../tools/tags.js';
+import { intelligenceTools } from '../tools/intelligence.js';
+import { healthTools } from '../tools/health.js';
+import { userTools } from '../tools/users.js';
+import { collaborationTools } from '../tools/collaboration.js';
+import { workflowTools } from '../tools/workflow.js';
+import { eventTools } from '../tools/events.js';
+import { clmTools } from '../tools/clm.js';
+import { complianceTools } from '../tools/compliance.js';
+/** All tool modules in registration order */
+const allToolModules = [
+    databaseTools,
+    ingestionTools,
+    searchTools,
+    documentTools,
+    provenanceTools,
+    configTools,
+    vlmTools,
+    imageTools,
+    evaluationTools,
+    extractionTools,
+    reportTools,
+    formFillTools,
+    structuredExtractionTools,
+    fileManagementTools,
+    comparisonTools,
+    clusteringTools,
+    chunkTools,
+    embeddingTools,
+    tagTools,
+    intelligenceTools,
+    healthTools,
+    userTools,
+    collaborationTools,
+    workflowTools,
+    eventTools,
+    clmTools,
+    complianceTools,
+];
+/**
+ * Register all tools on the given MCP server instance.
+ *
+ * @param server - McpServer instance to register tools on
+ * @returns Number of tools registered
+ * @throws Exits process with code 1 if duplicate tool names are detected
+ */
+export function registerAllTools(server) {
+    const registeredToolNames = new Set();
+    let toolCount = 0;
+    for (const toolModule of allToolModules) {
+        for (const [name, tool] of Object.entries(toolModule)) {
+            if (registeredToolNames.has(name)) {
+                console.error(`[FATAL] Duplicate tool name detected: "${name}". Each tool must have a unique name.`);
+                process.exit(1);
+            }
+            registeredToolNames.add(name);
+            server.tool(name, tool.description, tool.inputSchema, tool.handler);
+            toolCount++;
+        }
+    }
+    return toolCount;
+}
+/**
+ * Get total tool count without registering on a server instance.
+ * Used by HTTP mode health endpoint to avoid creating a throwaway McpServer.
+ */
+export function getToolCount() {
+    let count = 0;
+    for (const toolModule of allToolModules) {
+        count += Object.keys(toolModule).length;
+    }
+    return count;
+}
+//# sourceMappingURL=register-tools.js.map

package/dist/server/register-tools.js.map

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

package/dist/server/startup.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Shared Startup Validation
+ *
+ * Validates startup dependencies and applies environment-driven config.
+ * Used by both src/index.ts (stdio) and src/bin-http.ts (unified Docker entry).
+ *
+ * CRITICAL: NEVER use console.log() - stdout may be reserved for JSON-RPC protocol.
+ *
+ * @module server/startup
+ */
+/**
+ * Validate startup dependencies and apply environment-driven config overrides.
+ * Warnings only: missing API keys prevent specific features, not the whole server.
+ */
+export declare function validateStartupDependencies(): void;
+//# sourceMappingURL=startup.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"startup.d.ts","sourceRoot":"","sources":["../../src/server/startup.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAIH;;;GAGG;AACH,wBAAgB,2BAA2B,IAAI,IAAI,CA2BlD"}

package/dist/server/startup.js

@@ -0,0 +1,37 @@
+/**
+ * Shared Startup Validation
+ *
+ * Validates startup dependencies and applies environment-driven config.
+ * Used by both src/index.ts (stdio) and src/bin-http.ts (unified Docker entry).
+ *
+ * CRITICAL: NEVER use console.log() - stdout may be reserved for JSON-RPC protocol.
+ *
+ * @module server/startup
+ */
+import { updateConfig } from './state.js';
+/**
+ * Validate startup dependencies and apply environment-driven config overrides.
+ * Warnings only: missing API keys prevent specific features, not the whole server.
+ */
+export function validateStartupDependencies() {
+    const warnings = [];
+    if (!process.env.DATALAB_API_KEY) {
+        warnings.push('DATALAB_API_KEY is not set. OCR processing will fail. Get one at https://www.datalab.to');
+    }
+    if (!process.env.GEMINI_API_KEY) {
+        warnings.push('GEMINI_API_KEY is not set. VLM processing and evaluation will fail. Get one at https://aistudio.google.com/');
+    }
+    if (warnings.length > 0) {
+        console.error('=== STARTUP WARNINGS ===');
+        for (const w of warnings) {
+            console.error(`  - ${w}`);
+        }
+        console.error('========================');
+    }
+    const embeddingDevice = process.env.EMBEDDING_DEVICE;
+    if (embeddingDevice) {
+        updateConfig({ embeddingDevice });
+        console.error(`[Config] EMBEDDING_DEVICE=${embeddingDevice}`);
+    }
+}
+//# sourceMappingURL=startup.js.map

package/dist/server/startup.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"startup.js","sourceRoot":"","sources":["../../src/server/startup.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAE1C;;;GAGG;AACH,MAAM,UAAU,2BAA2B;IACzC,MAAM,QAAQ,GAAa,EAAE,CAAC;IAE9B,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,eAAe,EAAE,CAAC;QACjC,QAAQ,CAAC,IAAI,CACX,yFAAyF,CAC1F,CAAC;IACJ,CAAC;IACD,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,cAAc,EAAE,CAAC;QAChC,QAAQ,CAAC,IAAI,CACX,6GAA6G,CAC9G,CAAC;IACJ,CAAC;IAED,IAAI,QAAQ,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACxB,OAAO,CAAC,KAAK,CAAC,0BAA0B,CAAC,CAAC;QAC1C,KAAK,MAAM,CAAC,IAAI,QAAQ,EAAE,CAAC;YACzB,OAAO,CAAC,KAAK,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC;QAC5B,CAAC;QACD,OAAO,CAAC,KAAK,CAAC,0BAA0B,CAAC,CAAC;IAC5C,CAAC;IAED,MAAM,eAAe,GAAG,OAAO,CAAC,GAAG,CAAC,gBAAgB,CAAC;IACrD,IAAI,eAAe,EAAE,CAAC;QACpB,YAAY,CAAC,EAAE,eAAe,EAAE,CAAC,CAAC;QAClC,OAAO,CAAC,KAAK,CAAC,6BAA6B,eAAe,EAAE,CAAC,CAAC;IAChE,CAAC;AACH,CAAC"}

package/dist/server/state.d.ts

@@ -0,0 +1,166 @@
+/**
+ * MCP Server State Management
+ *
+ * Manages global server state including current database connection and configuration.
+ * FAIL FAST: All state access throws immediately if preconditions not met.
+ *
+ * @module server/state
+ */
+import { DatabaseService } from '../services/storage/database/index.js';
+import { VectorService } from '../services/storage/vector.js';
+import type { ServerState, ServerConfig } from './types.js';
+/**
+ * Global server state
+ * Mutable state for current database and configuration
+ */
+export declare const state: ServerState;
+/**
+ * Services returned from requireDatabase
+ */
+interface DatabaseServices {
+    db: DatabaseService;
+    vector: VectorService;
+    /** Generation counter for detecting stale references */
+    generation: number;
+}
+/**
+ * Require database to be selected - FAIL FAST if not
+ *
+ * @returns Database service, vector service, and generation counter
+ * @throws MCPError with DATABASE_NOT_SELECTED if no database is selected
+ */
+export declare function requireDatabase(): DatabaseServices;
+/**
+ * Validate that the database generation matches the expected value.
+ *
+ * The generation counter increments on every database switch/clear. A mismatch
+ * means the database was switched between the time a caller obtained the
+ * generation and the time it validates -- indicating a race condition where
+ * the caller's database reference is stale.
+ *
+ * Callers can optionally use this at critical points (e.g., before writing
+ * results back to the database) to detect and fail fast on stale references.
+ *
+ * @param expectedGeneration - The generation value obtained from requireDatabase()
+ * @throws Error if the current generation does not match
+ */
+export declare function validateGeneration(expectedGeneration: number): void;
+/**
+ * Begin tracking an in-flight database operation.
+ *
+ * Increments the active operation counter and returns the current generation.
+ * While any operations are active, selectDatabase() and clearDatabase() will
+ * throw to prevent database switches during async work.
+ *
+ * @returns Current database generation for later validation
+ * @throws MCPError if no database is selected
+ */
+export declare function beginDatabaseOperation(): number;
+/**
+ * End tracking an in-flight database operation.
+ *
+ * Decrements the active operation counter. Counter never goes below 0.
+ */
+export declare function endDatabaseOperation(): void;
+/**
+ * Get the number of active database operations (for diagnostics/testing).
+ */
+export declare function getActiveOperationCount(): number;
+/**
+ * Execute an async function within a tracked database operation scope.
+ *
+ * Calls beginDatabaseOperation() before the function and endDatabaseOperation()
+ * in a finally block, guaranteeing the counter is decremented even on error.
+ * Also validates the generation after the function completes to detect any
+ * mid-operation database switch.
+ *
+ * Use this for async tool handlers that do database writes across multiple
+ * await points. Read-only synchronous handlers do not need this wrapper
+ * because the event loop does not yield.
+ *
+ * @param fn - Async function receiving DatabaseServices
+ * @returns The result of fn
+ * @throws MCPError if no database is selected
+ * @throws Error if the database was switched during the operation
+ */
+export declare function withDatabaseOperation<T>(fn: (services: DatabaseServices) => Promise<T>): Promise<T>;
+/**
+ * Check if a database is currently selected
+ */
+export declare function hasDatabase(): boolean;
+/**
+ * Get current database name or null
+ */
+export declare function getCurrentDatabaseName(): string | null;
+/**
+ * Select a database by name - opens connection and sets as current
+ *
+ * FAIL FAST: Throws immediately if database doesn't exist or if operations
+ * are in-flight (H-2 guard). Uses atomic swap (M-9 fix): opens new DB first,
+ * then swaps state, then closes old DB -- no null window.
+ *
+ * @param name - Database name to select
+ * @param storagePath - Optional storage path override
+ * @throws MCPError with DATABASE_NOT_FOUND if database doesn't exist
+ * @throws Error if database operations are in-flight
+ */
+export declare function selectDatabase(name: string, storagePath?: string): void;
+/**
+ * Create a new database and optionally select it
+ *
+ * FAIL FAST: Throws immediately if database already exists
+ *
+ * @param name - Database name to create
+ * @param description - Optional description
+ * @param storagePath - Optional storage path override
+ * @param autoSelect - Whether to select the database after creation (default: true)
+ * @returns The created database service
+ * @throws MCPError with DATABASE_ALREADY_EXISTS if database exists
+ */
+export declare function createDatabase(name: string, description?: string, storagePath?: string, autoSelect?: boolean): DatabaseService;
+/**
+ * Delete a database
+ *
+ * FAIL FAST: Throws if database doesn't exist
+ *
+ * @param name - Database name to delete
+ * @param storagePath - Optional storage path override
+ * @throws MCPError with DATABASE_NOT_FOUND if database doesn't exist
+ */
+export declare function deleteDatabase(name: string, storagePath?: string): void;
+/**
+ * Clear current database selection - closes connection.
+ *
+ * FAIL FAST: Throws if async operations are in-flight (H-2 guard).
+ * The forceClose parameter bypasses the guard for internal use only
+ * (resetState in tests, process exit cleanup).
+ *
+ * @param forceClose - Skip operation guard (internal use only)
+ * @throws Error if database operations are in-flight and forceClose is false
+ */
+export declare function clearDatabase(forceClose?: boolean): void;
+/**
+ * Get current server configuration
+ */
+export declare function getConfig(): ServerConfig;
+/**
+ * Update server configuration (deep merges nested objects like imageOptimization)
+ */
+export declare function updateConfig(updates: Partial<ServerConfig>): void;
+/**
+ * Reset configuration to defaults
+ */
+export declare function resetConfig(): void;
+/**
+ * Get default storage path
+ */
+export declare function getDefaultStoragePath(): string;
+/**
+ * Reset all server state - ONLY USE IN TESTS
+ *
+ * Uses forceClose=true to bypass the operation guard since tests
+ * need to reset state unconditionally between test cases.
+ */
+export declare function resetState(): void;
+export {};
+//# sourceMappingURL=state.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"state.d.ts","sourceRoot":"","sources":["../../src/server/state.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,eAAe,EAAE,MAAM,uCAAuC,CAAC;AACxE,OAAO,EAAE,aAAa,EAAE,MAAM,+BAA+B,CAAC;AAQ9D,OAAO,KAAK,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAmC5D;;;GAGG;AACH,eAAO,MAAM,KAAK,EAAE,WAInB,CAAC;AAMF;;GAEG;AACH,UAAU,gBAAgB;IACxB,EAAE,EAAE,eAAe,CAAC;IACpB,MAAM,EAAE,aAAa,CAAC;IACtB,wDAAwD;IACxD,UAAU,EAAE,MAAM,CAAC;CACpB;AAkBD;;;;;GAKG;AACH,wBAAgB,eAAe,IAAI,gBAAgB,CASlD;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,kBAAkB,CAAC,kBAAkB,EAAE,MAAM,GAAG,IAAI,CAOnE;AAMD;;;;;;;;;GASG;AACH,wBAAgB,sBAAsB,IAAI,MAAM,CAM/C;AAED;;;;GAIG;AACH,wBAAgB,oBAAoB,IAAI,IAAI,CAI3C;AAED;;GAEG;AACH,wBAAgB,uBAAuB,IAAI,MAAM,CAEhD;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAsB,qBAAqB,CAAC,CAAC,EAC3C,EAAE,EAAE,CAAC,QAAQ,EAAE,gBAAgB,KAAK,OAAO,CAAC,CAAC,CAAC,GAC7C,OAAO,CAAC,CAAC,CAAC,CAUZ;AAED;;GAEG;AACH,wBAAgB,WAAW,IAAI,OAAO,CAErC;AAED;;GAEG;AACH,wBAAgB,sBAAsB,IAAI,MAAM,GAAG,IAAI,CAEtD;AAsDD;;;;;;;;;;;GAWG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,CAoCvE;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,cAAc,CAC5B,IAAI,EAAE,MAAM,EACZ,WAAW,CAAC,EAAE,MAAM,EACpB,WAAW,CAAC,EAAE,MAAM,EACpB,UAAU,GAAE,OAAc,GACzB,eAAe,CAmCjB;AAED;;;;;;;;GAQG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,CAevE;AAED;;;;;;;;;GASG;AACH,wBAAgB,aAAa,CAAC,UAAU,GAAE,OAAe,GAAG,IAAI,CAgB/D;AAMD;;GAEG;AACH,wBAAgB,SAAS,IAAI,YAAY,CAExC;AAED;;GAEG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,OAAO,CAAC,YAAY,CAAC,GAAG,IAAI,CAYjE;AAED;;GAEG;AACH,wBAAgB,WAAW,IAAI,IAAI,CAElC;AAED;;GAEG;AACH,wBAAgB,qBAAqB,IAAI,MAAM,CAE9C;AAMD;;;;;GAKG;AACH,wBAAgB,UAAU,IAAI,IAAI,CAMjC"}