promptspeak-mcp-server 0.1.0

package/dist/recon/persistence/index.js

@@ -0,0 +1,118 @@
+/**
+ * ═══════════════════════════════════════════════════════════════════════════════
+ * RECON PERSISTENCE MODULE
+ * ═══════════════════════════════════════════════════════════════════════════════
+ *
+ * Persistence layer for Marine Recon symbols. This module provides filesystem-based
+ * storage for MarineReconSymbol objects with features including:
+ *
+ * - Atomic writes to prevent corruption
+ * - File locking for concurrent access safety
+ * - Automatic backup creation
+ * - Symbol validation on load
+ * - Flexible filtering and pagination for listing
+ * - Optional in-memory caching
+ *
+ * @example Basic Usage
+ * ```typescript
+ * import { ReconSymbolStorage } from './persistence';
+ *
+ * const storage = new ReconSymbolStorage('/path/to/symbols');
+ * await storage.initialize();
+ *
+ * // Save a symbol
+ * await storage.save(mySymbol);
+ *
+ * // Load a symbol
+ * const symbol = await storage.load('Ξ.RECON.MY_MISSION');
+ *
+ * // List all symbols
+ * const result = await storage.list();
+ * console.log(result.symbols);
+ *
+ * // Delete a symbol
+ * await storage.delete('Ξ.RECON.MY_MISSION');
+ * ```
+ *
+ * @example With Options
+ * ```typescript
+ * const storage = new ReconSymbolStorage('/path/to/symbols', {
+ *   atomicWrites: true,
+ *   maxBackups: 5,
+ *   enableCache: true,
+ *   cacheMaxSize: 50,
+ * });
+ * ```
+ *
+ * @example Filtering and Pagination
+ * ```typescript
+ * const result = await storage.list({
+ *   filter: {
+ *     status: ['active', 'paused'],
+ *     namespace: 'production',
+ *     createdAfter: '2025-01-01',
+ *   },
+ *   sort: {
+ *     field: 'created_at',
+ *     direction: 'desc',
+ *   },
+ *   pagination: {
+ *     limit: 10,
+ *     offset: 0,
+ *   },
+ * });
+ * ```
+ *
+ * @example Event Handling
+ * ```typescript
+ * storage.on(StorageEvent.SYMBOL_SAVED, (payload) => {
+ *   console.log(`Symbol saved: ${payload.symbolId}`);
+ * });
+ *
+ * storage.on(StorageEvent.STORAGE_ERROR, (payload) => {
+ *   console.error('Storage error:', payload.details);
+ * });
+ * ```
+ *
+ * ═══════════════════════════════════════════════════════════════════════════════
+ */
+// ═══════════════════════════════════════════════════════════════════════════════
+// EXPORTS
+// ═══════════════════════════════════════════════════════════════════════════════
+// Main storage class
+export { ReconSymbolStorage } from './storage';
+// Types
+export { DEFAULT_STORAGE_OPTIONS, 
+// Error handling
+StorageError, StorageErrorCode, 
+// Events
+StorageEvent, } from './types';
+// ═══════════════════════════════════════════════════════════════════════════════
+// CONVENIENCE FACTORY
+// ═══════════════════════════════════════════════════════════════════════════════
+import { ReconSymbolStorage } from './storage';
+/**
+ * Create and initialize a ReconSymbolStorage instance.
+ * This is a convenience function that handles initialization.
+ *
+ * @param basePath - Base directory for storing symbol files
+ * @param options - Storage configuration options
+ * @returns Initialized storage instance
+ *
+ * @example
+ * ```typescript
+ * const storage = await createStorage('/path/to/symbols');
+ * // Storage is ready to use immediately
+ * ```
+ */
+export async function createStorage(basePath, options) {
+    const storage = new ReconSymbolStorage(basePath, options);
+    await storage.initialize();
+    return storage;
+}
+/**
+ * Default storage location relative to the project.
+ * Used when no explicit path is provided.
+ */
+export const DEFAULT_STORAGE_PATH = '.recon-symbols';
+//# sourceMappingURL=index.js.map

package/dist/recon/persistence/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/recon/persistence/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6EG;AAEH,kFAAkF;AAClF,UAAU;AACV,kFAAkF;AAElF,qBAAqB;AACrB,OAAO,EAAE,kBAAkB,EAAE,MAAM,WAAW,CAAC;AAE/C,QAAQ;AACR,OAAO,EAIL,uBAAuB;AAEvB,iBAAiB;AACjB,YAAY,EACZ,gBAAgB;AAShB,SAAS;AACT,YAAY,GAGb,MAAM,SAAS,CAAC;AAEjB,kFAAkF;AAClF,sBAAsB;AACtB,kFAAkF;AAElF,OAAO,EAAE,kBAAkB,EAAE,MAAM,WAAW,CAAC;AAG/C;;;;;;;;;;;;;GAaG;AACH,MAAM,CAAC,KAAK,UAAU,aAAa,CACjC,QAAgB,EAChB,OAAwB;IAExB,MAAM,OAAO,GAAG,IAAI,kBAAkB,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;IAC1D,MAAM,OAAO,CAAC,UAAU,EAAE,CAAC;IAC3B,OAAO,OAAO,CAAC;AACjB,CAAC;AAED;;;GAGG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAG,gBAAgB,CAAC"}

package/dist/recon/persistence/storage.d.ts

@@ -0,0 +1,166 @@
+/**
+ * ═══════════════════════════════════════════════════════════════════════════════
+ * RECON SYMBOL STORAGE
+ * ═══════════════════════════════════════════════════════════════════════════════
+ *
+ * Persistence layer for Marine Recon symbols. Handles saving, loading, listing,
+ * and deleting symbols from the filesystem.
+ *
+ * Features:
+ * - Atomic writes to prevent corruption
+ * - File locking for concurrent access safety
+ * - Automatic backup creation
+ * - Symbol validation on load
+ * - Optional in-memory caching
+ *
+ * ═══════════════════════════════════════════════════════════════════════════════
+ */
+import { MarineReconSymbol } from '../types';
+import { StorageOptions, ListOptions, ListResult, SymbolFilter, StorageEvent, StorageEventListener } from './types';
+/**
+ * Storage class for persisting Marine Recon symbols to the filesystem.
+ */
+export declare class ReconSymbolStorage {
+    private readonly basePath;
+    private readonly options;
+    private readonly fileLock;
+    private readonly cache;
+    private readonly eventListeners;
+    private initialized;
+    /**
+     * Create a new ReconSymbolStorage instance.
+     *
+     * @param basePath - Base directory for storing symbol files
+     * @param options - Storage configuration options
+     */
+    constructor(basePath: string, options?: StorageOptions);
+    /**
+     * Initialize the storage, creating the directory if needed.
+     */
+    initialize(): Promise<void>;
+    /**
+     * Ensure storage is initialized before operations.
+     */
+    private ensureInitialized;
+    /**
+     * Save a symbol to storage.
+     *
+     * @param symbol - The MarineReconSymbol to save
+     * @throws StorageError if save fails
+     */
+    save(symbol: MarineReconSymbol): Promise<void>;
+    /**
+     * Load a symbol from storage.
+     *
+     * @param symbolId - The symbol ID to load
+     * @returns The loaded symbol or null if not found
+     * @throws StorageError if load fails (other than not found)
+     */
+    load(symbolId: string): Promise<MarineReconSymbol | null>;
+    /**
+     * List all symbols in storage with optional filtering and pagination.
+     *
+     * @param options - List options (filter, sort, pagination)
+     * @returns List result with symbols and metadata
+     */
+    list(options?: ListOptions): Promise<ListResult>;
+    /**
+     * Delete a symbol from storage.
+     *
+     * @param symbolId - The symbol ID to delete
+     * @returns true if deleted, false if not found
+     */
+    delete(symbolId: string): Promise<boolean>;
+    /**
+     * Check if a symbol exists in storage.
+     *
+     * @param symbolId - The symbol ID to check
+     * @returns true if exists, false otherwise
+     */
+    exists(symbolId: string): Promise<boolean>;
+    /**
+     * Save a symbol only if it doesn't already exist.
+     *
+     * @param symbol - The symbol to save
+     * @throws StorageError.ALREADY_EXISTS if symbol exists
+     */
+    saveIfNotExists(symbol: MarineReconSymbol): Promise<void>;
+    /**
+     * Update a symbol with optimistic locking (version check).
+     *
+     * @param symbol - The symbol to update
+     * @param expectedVersion - Expected current version
+     * @throws StorageError.VERSION_CONFLICT if versions don't match
+     */
+    updateWithVersionCheck(symbol: MarineReconSymbol, expectedVersion: number): Promise<void>;
+    /**
+     * Get symbol count matching optional filter.
+     */
+    count(filter?: SymbolFilter): Promise<number>;
+    /**
+     * Clear all symbols from storage.
+     * USE WITH CAUTION!
+     */
+    clear(): Promise<number>;
+    /**
+     * Subscribe to storage events.
+     */
+    on(event: StorageEvent, listener: StorageEventListener): void;
+    /**
+     * Unsubscribe from storage events.
+     */
+    off(event: StorageEvent, listener: StorageEventListener): void;
+    /**
+     * Emit a storage event.
+     */
+    private emitEvent;
+    /**
+     * Convert a symbol ID to a safe file name.
+     */
+    private symbolIdToFileName;
+    /**
+     * Extract symbol ID from file name.
+     */
+    private fileNameToSymbolId;
+    /**
+     * Perform an atomic write operation.
+     */
+    private atomicWrite;
+    /**
+     * Create a backup of a symbol file.
+     */
+    private createBackup;
+    /**
+     * Clean old backups beyond the maximum count.
+     */
+    private cleanOldBackups;
+    /**
+     * Load a symbol summary from a file.
+     */
+    private loadSummary;
+    /**
+     * Check if a summary matches filter criteria.
+     */
+    private matchesFilter;
+    /**
+     * Sort summaries by specified field.
+     */
+    private sortSummaries;
+    /**
+     * Validate a symbol's basic structure.
+     */
+    private validateSymbol;
+    /**
+     * Get the base storage path.
+     */
+    getBasePath(): string;
+    /**
+     * Get the current storage options.
+     */
+    getOptions(): Readonly<Required<StorageOptions>>;
+    /**
+     * Check if storage is initialized.
+     */
+    isInitialized(): boolean;
+}
+//# sourceMappingURL=storage.d.ts.map

package/dist/recon/persistence/storage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"storage.d.ts","sourceRoot":"","sources":["../../../src/recon/persistence/storage.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAKH,OAAO,EAAE,iBAAiB,EAAE,MAAM,UAAU,CAAC;AAE7C,OAAO,EAEL,cAAc,EAGd,WAAW,EACX,UAAU,EACV,YAAY,EAEZ,YAAY,EAEZ,oBAAoB,EAErB,MAAM,SAAS,CAAC;AA4HjB;;GAEG;AACH,qBAAa,kBAAkB;IAC7B,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA2B;IACnD,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAW;IACpC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAqC;IAC3D,OAAO,CAAC,QAAQ,CAAC,cAAc,CAA2D;IAC1F,OAAO,CAAC,WAAW,CAAkB;IAErC;;;;;OAKG;gBACS,QAAQ,EAAE,MAAM,EAAE,OAAO,GAAE,cAAmB;IAa1D;;OAEG;IACG,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IA2BjC;;OAEG;YACW,iBAAiB;IAU/B;;;;;OAKG;IACG,IAAI,CAAC,MAAM,EAAE,iBAAiB,GAAG,OAAO,CAAC,IAAI,CAAC;IAoDpD;;;;;;OAMG;IACG,IAAI,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,GAAG,IAAI,CAAC;IA2D/D;;;;;OAKG;IACG,IAAI,CAAC,OAAO,GAAE,WAAgB,GAAG,OAAO,CAAC,UAAU,CAAC;IA0C1D;;;;;OAKG;IACG,MAAM,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAiChD;;;;;OAKG;IACG,MAAM,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAuBhD;;;;;OAKG;IACG,eAAe,CAAC,MAAM,EAAE,iBAAiB,GAAG,OAAO,CAAC,IAAI,CAAC;IAO/D;;;;;;OAMG;IACG,sBAAsB,CAC1B,MAAM,EAAE,iBAAiB,EACzB,eAAe,EAAE,MAAM,GACtB,OAAO,CAAC,IAAI,CAAC;IAehB;;OAEG;IACG,KAAK,CAAC,MAAM,CAAC,EAAE,YAAY,GAAG,OAAO,CAAC,MAAM,CAAC;IAKnD;;;OAGG;IACG,KAAK,IAAI,OAAO,CAAC,MAAM,CAAC;IA6B9B;;OAEG;IACH,EAAE,CAAC,KAAK,EAAE,YAAY,EAAE,QAAQ,EAAE,oBAAoB,GAAG,IAAI;IAO7D;;OAEG;IACH,GAAG,CAAC,KAAK,EAAE,YAAY,EAAE,QAAQ,EAAE,oBAAoB,GAAG,IAAI;IAI9D;;OAEG;IACH,OAAO,CAAC,SAAS;IAyBjB;;OAEG;IACH,OAAO,CAAC,kBAAkB;IAY1B;;OAEG;IACH,OAAO,CAAC,kBAAkB;IAc1B;;OAEG;YACW,WAAW;IAyBzB;;OAEG;YACW,YAAY;IAiB1B;;OAEG;YACW,eAAe;IAqB7B;;OAEG;YACW,WAAW;IA0BzB;;OAEG;IACH,OAAO,CAAC,aAAa;IAkFrB;;OAEG;IACH,OAAO,CAAC,aAAa;IAsDrB;;OAEG;IACH,OAAO,CAAC,cAAc;IAyBtB;;OAEG;IACH,WAAW,IAAI,MAAM;IAIrB;;OAEG;IACH,UAAU,IAAI,QAAQ,CAAC,QAAQ,CAAC,cAAc,CAAC,CAAC;IAIhD;;OAEG;IACH,aAAa,IAAI,OAAO;CAGzB"}