@xnetjs/plugins 0.0.2

package/dist/services/node.d.ts

@@ -0,0 +1,583 @@
+/**
+ * Local HTTP API Server
+ *
+ * Provides a REST API for external integrations (N8N, MCP, etc.) to interact
+ * with xNet data. Runs on localhost only (port 31415 by default).
+ *
+ * This is designed to run in the Electron main process.
+ */
+/**
+ * Node store interface (minimal subset needed by API)
+ */
+interface NodeStoreAPI {
+    get(id: string): Promise<NodeData | null>;
+    list(options?: {
+        schemaId?: string;
+        limit?: number;
+        offset?: number;
+    }): Promise<NodeData[]>;
+    create(options: {
+        schemaId: string;
+        properties: Record<string, unknown>;
+    }): Promise<NodeData>;
+    update(id: string, options: {
+        properties: Record<string, unknown>;
+    }): Promise<NodeData>;
+    delete(id: string): Promise<void>;
+    subscribe(listener: (event: NodeChangeEventData) => void): () => void;
+}
+/**
+ * Schema registry interface (minimal subset needed by API)
+ */
+interface SchemaRegistryAPI {
+    getAllIRIs(): string[];
+    get(iri: string): Promise<SchemaData | null>;
+}
+/**
+ * Node data returned by API
+ */
+interface NodeData {
+    id: string;
+    schemaId: string;
+    properties: Record<string, unknown>;
+    deleted: boolean;
+    createdAt: number;
+    updatedAt: number;
+}
+/**
+ * Schema data returned by API
+ */
+interface SchemaData {
+    iri: string;
+    name: string;
+    properties: Record<string, unknown>;
+}
+/**
+ * Node change event data
+ */
+interface NodeChangeEventData {
+    change: {
+        type: string;
+    };
+    node: NodeData | null;
+    isRemote: boolean;
+}
+/**
+ * API configuration
+ */
+interface LocalAPIConfig {
+    /** Port to listen on (default: 31415) */
+    port?: number;
+    /** Host to bind to (default: '127.0.0.1') */
+    host?: string;
+    /** API token for authentication (optional) */
+    token?: string;
+    /**
+     * Allowed CORS origins (default: none).
+     * Set to specific origins like ['http://localhost:3000'] for local dev,
+     * or ['*'] to allow all origins (not recommended for production).
+     * Empty array or undefined disables CORS entirely.
+     */
+    allowedOrigins?: string[];
+    /** NodeStore instance */
+    store: NodeStoreAPI;
+    /** SchemaRegistry instance */
+    schemas: SchemaRegistryAPI;
+}
+/**
+ * Local HTTP API server for xNet integrations.
+ */
+declare class LocalAPIServer {
+    private server;
+    private config;
+    private eventBuffer;
+    private unsubscribe?;
+    constructor(config: LocalAPIConfig);
+    /**
+     * Start the API server
+     */
+    start(): Promise<void>;
+    /**
+     * Stop the API server
+     */
+    stop(): Promise<void>;
+    /**
+     * Get the server port
+     */
+    get port(): number;
+    /**
+     * Check if server is running
+     */
+    get isRunning(): boolean;
+    private handleRequest;
+    private handleHealth;
+    private handleListNodes;
+    private handleGetNode;
+    private handleCreateNode;
+    private handleUpdateNode;
+    private handleDeleteNode;
+    private handleQuery;
+    private handleGetEvents;
+    private handleListSchemas;
+    private handleGetSchema;
+    private parseBody;
+    private sendJSON;
+    private sendError;
+    private getEventType;
+}
+/**
+ * Create a local API server.
+ *
+ * @example
+ * ```typescript
+ * const api = createLocalAPI({
+ *   port: 31415,
+ *   store: nodeStore,
+ *   schemas: schemaRegistry
+ * })
+ *
+ * await api.start()
+ * // Server is now listening on http://127.0.0.1:31415
+ *
+ * await api.stop()
+ * ```
+ */
+declare function createLocalAPI(config: LocalAPIConfig): LocalAPIServer;
+
+/**
+ * MCP Server for xNet
+ *
+ * Exposes xNet data to AI agents via the Model Context Protocol.
+ * Provides tools for querying, creating, and updating nodes.
+ *
+ * This runs as a stdio-based MCP server, typically spawned by an MCP client.
+ */
+
+/**
+ * MCP Tool definition
+ */
+interface MCPTool {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: 'object';
+        properties: Record<string, MCPPropertySchema>;
+        required?: string[];
+    };
+}
+/**
+ * MCP property schema
+ */
+interface MCPPropertySchema {
+    type: 'string' | 'number' | 'boolean' | 'object' | 'array';
+    description?: string;
+    items?: MCPPropertySchema;
+}
+/**
+ * MCP Resource definition
+ */
+interface MCPResource {
+    uri: string;
+    name: string;
+    description?: string;
+    mimeType?: string;
+}
+/**
+ * MCP Request from client
+ */
+interface MCPRequest {
+    jsonrpc: '2.0';
+    id: number | string;
+    method: string;
+    params?: Record<string, unknown>;
+}
+/**
+ * MCP Response to client
+ */
+interface MCPResponse {
+    jsonrpc: '2.0';
+    id: number | string;
+    result?: unknown;
+    error?: {
+        code: number;
+        message: string;
+        data?: unknown;
+    };
+}
+/**
+ * MCP Server configuration
+ */
+interface MCPServerConfig {
+    store: NodeStoreAPI;
+    schemas: SchemaRegistryAPI;
+    /** Server name (default: 'xnet') */
+    name?: string;
+    /** Server version (default: '1.0.0') */
+    version?: string;
+}
+/**
+ * MCP Server for xNet.
+ *
+ * Provides tools for AI agents to interact with xNet data:
+ * - xnet_query: Query nodes by schema and filter
+ * - xnet_create: Create a new node
+ * - xnet_update: Update an existing node
+ * - xnet_delete: Delete a node
+ * - xnet_search: Full-text search across nodes
+ * - xnet_schemas: List available schemas
+ *
+ * @example
+ * ```typescript
+ * const server = new MCPServer({
+ *   store: nodeStore,
+ *   schemas: schemaRegistry
+ * })
+ *
+ * // Start stdio server (for MCP client connections)
+ * await server.startStdio()
+ * ```
+ */
+declare class MCPServer {
+    private config;
+    private tools;
+    private running;
+    constructor(config: MCPServerConfig);
+    /**
+     * Get server info for MCP initialize response
+     */
+    getServerInfo(): {
+        name: string;
+        version: string;
+    };
+    /**
+     * Get server capabilities
+     */
+    getCapabilities(): {
+        tools: Record<string, never>;
+        resources: Record<string, never>;
+    };
+    /**
+     * Get all registered tools
+     */
+    getTools(): MCPTool[];
+    /**
+     * Get available resources
+     */
+    getResources(): MCPResource[];
+    /**
+     * Handle an MCP request
+     */
+    handleRequest(request: MCPRequest): Promise<MCPResponse>;
+    /**
+     * Start the MCP server in stdio mode.
+     * Reads JSON-RPC requests from stdin and writes responses to stdout.
+     */
+    startStdio(): Promise<void>;
+    /**
+     * Stop the stdio server
+     */
+    stop(): void;
+    private registerTools;
+    private handleToolCall;
+    private handleResourceRead;
+}
+/**
+ * Create an MCP server for xNet.
+ *
+ * @example
+ * ```typescript
+ * const server = createMCPServer({
+ *   store: nodeStore,
+ *   schemas: schemaRegistry
+ * })
+ *
+ * // Handle individual requests
+ * const response = await server.handleRequest(request)
+ *
+ * // Or start as a stdio server
+ * await server.startStdio()
+ * ```
+ */
+declare function createMCPServer(config: MCPServerConfig): MCPServer;
+
+/**
+ * Service Plugin Types
+ *
+ * Defines the types for background service plugins that run as separate processes.
+ * These are primarily used in Electron but the types are shared.
+ */
+/**
+ * Process configuration for a service
+ */
+interface ServiceProcessConfig {
+    /** Executable command (e.g., 'node', 'python', 'ollama') */
+    command: string;
+    /** Command arguments */
+    args?: string[];
+    /** Working directory */
+    cwd?: string;
+    /** Environment variables */
+    env?: Record<string, string>;
+    /** Run in shell (for PATH resolution) */
+    shell?: boolean;
+}
+/**
+ * Health check configuration
+ */
+interface ServiceHealthCheck {
+    /** Type of health check */
+    type: 'http' | 'stdout' | 'tcp';
+    /** URL to check for HTTP health checks */
+    url?: string;
+    /** Port to check for TCP health checks */
+    port?: number;
+    /** Regex pattern to match in stdout */
+    pattern?: string;
+    /** Interval between checks in milliseconds (default: 5000) */
+    intervalMs?: number;
+    /** Timeout for each check in milliseconds (default: 5000) */
+    timeoutMs?: number;
+}
+/**
+ * Lifecycle configuration for a service
+ */
+interface ServiceLifecycle {
+    /** Restart policy */
+    restart: 'always' | 'on-failure' | 'never';
+    /** Maximum number of restarts (default: 5) */
+    maxRestarts?: number;
+    /** Delay between restarts in milliseconds (default: 1000) */
+    restartDelayMs?: number;
+    /** Timeout for service startup in milliseconds (default: 10000) */
+    startTimeoutMs?: number;
+    /** Health check configuration */
+    healthCheck?: ServiceHealthCheck;
+    /** Graceful shutdown timeout in milliseconds (default: 5000) */
+    shutdownTimeoutMs?: number;
+}
+/**
+ * Communication configuration for a service
+ */
+interface ServiceCommunication {
+    /** Communication protocol */
+    protocol: 'stdio' | 'http' | 'websocket' | 'ipc';
+    /** Port for HTTP/WebSocket (0 = auto-assign) */
+    port?: number;
+    /** Host address (default: '127.0.0.1') */
+    host?: string;
+}
+/**
+ * Capabilities provided by a service
+ */
+interface ServiceProvides {
+    /** MCP tool definitions */
+    mcp?: {
+        tools: string[];
+    };
+    /** HTTP API routes */
+    api?: {
+        routes: string[];
+    };
+}
+/**
+ * Complete service definition
+ */
+interface ServiceDefinition {
+    /** Unique service identifier */
+    id: string;
+    /** Human-readable name */
+    name: string;
+    /** Optional description */
+    description?: string;
+    /** Process configuration */
+    process: ServiceProcessConfig;
+    /** Lifecycle configuration */
+    lifecycle: ServiceLifecycle;
+    /** Communication configuration */
+    communication: ServiceCommunication;
+    /** Capabilities this service provides */
+    provides?: ServiceProvides;
+}
+/**
+ * Service state
+ */
+type ServiceState = 'starting' | 'running' | 'stopping' | 'stopped' | 'error';
+/**
+ * Service status
+ */
+interface ServiceStatus {
+    /** Service ID */
+    id: string;
+    /** Current state */
+    state: ServiceState;
+    /** Process ID (when running) */
+    pid?: number;
+    /** Port (when running with HTTP/WebSocket) */
+    port?: number;
+    /** Timestamp when service started */
+    startedAt?: number;
+    /** Last error message */
+    lastError?: string;
+    /** Number of restarts since initial start */
+    restartCount: number;
+    /** Uptime in milliseconds (if running) */
+    uptime?: number;
+}
+/**
+ * Event emitted when service status changes
+ */
+interface ServiceStatusEvent {
+    serviceId: string;
+    status: ServiceStatus;
+    previousState?: ServiceState;
+}
+/**
+ * Event emitted when service outputs data
+ */
+interface ServiceOutputEvent {
+    serviceId: string;
+    stream: 'stdout' | 'stderr';
+    data: string;
+    timestamp: number;
+}
+/**
+ * Client interface for interacting with services from the renderer process
+ */
+interface ServiceClient {
+    /** Start a service */
+    start(definition: ServiceDefinition): Promise<ServiceStatus>;
+    /** Stop a service */
+    stop(serviceId: string): Promise<void>;
+    /** Restart a service */
+    restart(serviceId: string): Promise<ServiceStatus>;
+    /** Get service status */
+    status(serviceId: string): Promise<ServiceStatus | undefined>;
+    /** Get all service statuses */
+    listAll(): Promise<ServiceStatus[]>;
+    /** Call a service via HTTP */
+    call<T>(serviceId: string, method: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE', path: string, body?: unknown): Promise<T>;
+    /** Subscribe to status changes */
+    onStatusChange(serviceId: string, callback: (status: ServiceStatus) => void): () => void;
+    /** Subscribe to service output */
+    onOutput(serviceId: string, callback: (event: ServiceOutputEvent) => void): () => void;
+}
+/**
+ * Events emitted by the ProcessManager
+ */
+interface ProcessManagerEvents {
+    'service:status': (event: ServiceStatusEvent) => void;
+    'service:output': (event: ServiceOutputEvent) => void;
+    'service:error': (event: {
+        serviceId: string;
+        error: Error;
+    }) => void;
+}
+/**
+ * Interface for the process manager (implemented in Electron main process)
+ */
+interface IProcessManager {
+    /** Start a service */
+    start(definition: ServiceDefinition): Promise<ServiceStatus>;
+    /** Stop a service */
+    stop(serviceId: string): Promise<void>;
+    /** Restart a service */
+    restart(serviceId: string): Promise<ServiceStatus>;
+    /** Get service status */
+    getStatus(serviceId: string): ServiceStatus | undefined;
+    /** Get all service statuses */
+    getAllStatuses(): ServiceStatus[];
+    /** Stop all services */
+    stopAll(): Promise<void>;
+    /** Subscribe to events */
+    on<K extends keyof ProcessManagerEvents>(event: K, listener: ProcessManagerEvents[K]): void;
+    /** Unsubscribe from events */
+    off<K extends keyof ProcessManagerEvents>(event: K, listener: ProcessManagerEvents[K]): void;
+}
+
+/**
+ * Process Manager
+ *
+ * Manages background service processes. This module is designed to run in
+ * Electron's main process or Node.js environment.
+ *
+ * Note: In browser environments, this will not work directly - use the
+ * ServiceClient with IPC to communicate with the main process.
+ */
+
+/**
+ * Manages multiple service processes
+ *
+ * @example
+ * ```typescript
+ * const manager = new ProcessManager()
+ *
+ * await manager.start({
+ *   id: 'ollama',
+ *   name: 'Ollama',
+ *   process: { command: 'ollama', args: ['serve'] },
+ *   lifecycle: { restart: 'on-failure' },
+ *   communication: { protocol: 'http', port: 11434 }
+ * })
+ *
+ * manager.on('service:status', (event) => {
+ *   console.log(`${event.serviceId}: ${event.status.state}`)
+ * })
+ * ```
+ */
+declare class ProcessManager implements IProcessManager {
+    private processes;
+    private listeners;
+    /**
+     * Start a service
+     */
+    start(definition: ServiceDefinition): Promise<ServiceStatus>;
+    /**
+     * Stop a service
+     */
+    stop(serviceId: string): Promise<void>;
+    /**
+     * Restart a service
+     */
+    restart(serviceId: string): Promise<ServiceStatus>;
+    /**
+     * Get service status
+     */
+    getStatus(serviceId: string): ServiceStatus | undefined;
+    /**
+     * Get all service statuses
+     */
+    getAllStatuses(): ServiceStatus[];
+    /**
+     * Stop all services
+     */
+    stopAll(): Promise<void>;
+    /**
+     * Subscribe to events
+     */
+    on<K extends keyof ProcessManagerEvents>(event: K, listener: ProcessManagerEvents[K]): void;
+    /**
+     * Unsubscribe from events
+     */
+    off<K extends keyof ProcessManagerEvents>(event: K, listener: ProcessManagerEvents[K]): void;
+    private emit;
+}
+
+/**
+ * Service Client
+ *
+ * Client API for interacting with services from the renderer process.
+ * Uses IPC to communicate with the ProcessManager in the main process.
+ */
+
+declare const SERVICE_IPC_CHANNELS: {
+    readonly START: "xnet:service:start";
+    readonly STOP: "xnet:service:stop";
+    readonly RESTART: "xnet:service:restart";
+    readonly STATUS: "xnet:service:status";
+    readonly LIST_ALL: "xnet:service:list-all";
+    readonly CALL: "xnet:service:call";
+    readonly STATUS_UPDATE: "xnet:service:status-update";
+    readonly OUTPUT: "xnet:service:output";
+};
+
+export { type IProcessManager, type LocalAPIConfig, LocalAPIServer, type MCPPropertySchema, type MCPRequest, type MCPResource, type MCPResponse, MCPServer, type MCPServerConfig, type MCPTool, type NodeChangeEventData, type NodeData, type NodeStoreAPI, ProcessManager, type ProcessManagerEvents, SERVICE_IPC_CHANNELS, type SchemaData, type SchemaRegistryAPI, type ServiceClient, type ServiceCommunication, type ServiceDefinition, type ServiceHealthCheck, type ServiceLifecycle, type ServiceOutputEvent, type ServiceProcessConfig, type ServiceProvides, type ServiceState, type ServiceStatus, type ServiceStatusEvent, createLocalAPI, createMCPServer };