holosphere 2.0.0-alpha21 → 2.0.0-alpha23

package/src/storage/migration.js

@@ -1,351 +0,0 @@
-/**
- * @fileoverview Migration tool for HoloSphere storage backends.
- * Enables data migration between different storage backends (Nostr, GunDB, ActivityPub)
- * with export/import functionality, direct migration, and validation.
- * @module storage/migration
- */
-
-import { BackendFactory } from './backend-factory.js';
-
-/**
- * Portable data bundle format
- * @typedef {Object} DataBundle
- * @property {string} version - Bundle format version
- * @property {string} exportedAt - ISO timestamp
- * @property {string} sourceType - Source backend type
- * @property {string} sourceKey - Source public key
- * @property {number} recordCount - Number of records
- * @property {Object[]} records - Array of data records
- */
-
-/**
- * Migration record format
- * @typedef {Object} MigrationRecord
- * @property {string} path - Storage path
- * @property {Object} data - Record data
- * @property {number} timestamp - Creation timestamp
- * @property {string} [author] - Author public key
- */
-
-/**
- * Migration results
- * @typedef {Object} MigrationResults
- * @property {number} success - Successfully migrated records
- * @property {number} failed - Failed records
- * @property {Object[]} errors - Error details
- */
-
-/**
- * Migration tool for transferring data between HoloSphere storage backends.
- * Supports export/import to portable format, direct migration, and validation.
- *
- * @class MigrationTool
- * @example
- * const tool = new MigrationTool();
- * await tool.setSource('nostr', { relays: ['wss://...'] });
- * await tool.setTarget('gundb', { peers: ['wss://...'] });
- * const results = await tool.migrate();
- */
-export class MigrationTool {
-  /**
-   * Create a new MigrationTool instance.
-   */
-  constructor() {
-    /** @type {StorageBackend|null} */
-    this.sourceBackend = null;
-    /** @type {StorageBackend|null} */
-    this.targetBackend = null;
-  }
-
-  /**
-   * Configure source backend
-   * @param {string} type - Backend type: 'nostr' | 'gundb' | 'activitypub'
-   * @param {Object} config - Backend configuration
-   * @returns {Promise<void>}
-   */
-  async setSource(type, config) {
-    this.sourceBackend = await BackendFactory.create(type, config);
-  }
-
-  /**
-   * Configure target backend
-   * @param {string} type - Backend type: 'nostr' | 'gundb' | 'activitypub'
-   * @param {Object} config - Backend configuration
-   * @returns {Promise<void>}
-   */
-  async setTarget(type, config) {
-    this.targetBackend = await BackendFactory.create(type, config);
-  }
-
-  /**
-   * Use an existing backend instance as source
-   * @param {StorageBackend} backend - Backend instance
-   */
-  useSourceBackend(backend) {
-    this.sourceBackend = backend;
-  }
-
-  /**
-   * Use an existing backend instance as target
-   * @param {StorageBackend} backend - Backend instance
-   */
-  useTargetBackend(backend) {
-    this.targetBackend = backend;
-  }
-
-  /**
-   * Export data from source to portable format
-   * @param {string} [pathPrefix] - Optional path prefix filter
-   * @returns {Promise<DataBundle>} Exportable data bundle
-   */
-  async export(pathPrefix = '') {
-    if (!this.sourceBackend) {
-      throw new Error('Source backend not configured. Call setSource() first.');
-    }
-
-    console.log(`Exporting data from ${this.sourceBackend.getStatus().type}...`);
-
-    const records = await this.sourceBackend.exportData(pathPrefix);
-    const status = this.sourceBackend.getStatus();
-
-    const bundle = {
-      version: '1.0',
-      exportedAt: new Date().toISOString(),
-      sourceType: status.type,
-      sourceKey: status.publicKey || 'unknown',
-      pathPrefix: pathPrefix || '',
-      recordCount: records.length,
-      records,
-    };
-
-    console.log(`Exported ${records.length} records.`);
-    return bundle;
-  }
-
-  /**
-   * Import data to target backend
-   * @param {DataBundle} bundle - Data bundle from export()
-   * @param {Object} [options] - Import options
-   * @param {boolean} [options.overwrite] - Overwrite existing data
-   * @param {boolean} [options.dryRun] - Simulate without writing
-   * @param {Function} [options.onProgress] - Progress callback (current, total)
-   * @returns {Promise<MigrationResults>} Import results
-   */
-  async import(bundle, options = {}) {
-    if (!this.targetBackend) {
-      throw new Error('Target backend not configured. Call setTarget() first.');
-    }
-
-    if (!bundle || !bundle.records) {
-      throw new Error('Invalid bundle format. Expected { version, records }');
-    }
-
-    console.log(`Importing ${bundle.recordCount} records to ${this.targetBackend.getStatus().type}...`);
-
-    if (options.dryRun) {
-      console.log('Dry run mode - no data will be written.');
-      return {
-        dryRun: true,
-        wouldImport: bundle.recordCount,
-        records: bundle.records.map(r => r.path),
-      };
-    }
-
-    const results = await this.targetBackend.importData(bundle.records, options);
-
-    if (options.onProgress) {
-      options.onProgress(results.success + results.failed, bundle.recordCount);
-    }
-
-    console.log(`Import complete: ${results.success} succeeded, ${results.failed} failed.`);
-    return results;
-  }
-
-  /**
-   * Migrate data directly from source to target
-   * @param {string} [pathPrefix] - Optional path prefix filter
-   * @param {Object} [options] - Migration options
-   * @param {boolean} [options.dryRun] - Simulate without writing
-   * @param {Function} [options.onProgress] - Progress callback
-   * @returns {Promise<Object>} Migration results
-   */
-  async migrate(pathPrefix = '', options = {}) {
-    if (!this.sourceBackend || !this.targetBackend) {
-      throw new Error('Both source and target backends must be configured.');
-    }
-
-    const sourceStatus = this.sourceBackend.getStatus();
-    const targetStatus = this.targetBackend.getStatus();
-
-    console.log(`\nMigrating data:`);
-    console.log(`  From: ${sourceStatus.type} (${sourceStatus.publicKey || 'unknown'})`);
-    console.log(`  To:   ${targetStatus.type}`);
-    console.log(`  Filter: ${pathPrefix || '(all data)'}\n`);
-
-    // Export from source
-    const bundle = await this.export(pathPrefix);
-
-    // Import to target
-    const importResults = await this.import(bundle, options);
-
-    return {
-      sourceType: sourceStatus.type,
-      targetType: targetStatus.type,
-      pathPrefix,
-      exportedCount: bundle.recordCount,
-      ...importResults,
-    };
-  }
-
-  /**
-   * Validate data integrity after migration
-   * @param {string} [pathPrefix] - Optional path prefix filter
-   * @returns {Promise<Object>} Validation results
-   */
-  async validate(pathPrefix = '') {
-    if (!this.sourceBackend || !this.targetBackend) {
-      throw new Error('Both source and target backends must be configured.');
-    }
-
-    console.log('Validating migration...');
-
-    const sourceData = await this.sourceBackend.exportData(pathPrefix);
-    const targetData = await this.targetBackend.exportData(pathPrefix);
-
-    const sourceMap = new Map(sourceData.map(r => [r.path, r]));
-    const targetMap = new Map(targetData.map(r => [r.path, r]));
-
-    const missing = [];
-    const different = [];
-    const extra = [];
-
-    // Check for missing or different records
-    for (const [path, sourceRecord] of sourceMap) {
-      const targetRecord = targetMap.get(path);
-
-      if (!targetRecord) {
-        missing.push(path);
-      } else {
-        // Compare data (ignoring metadata that may differ)
-        const sourceDataStr = JSON.stringify(this._normalizeForComparison(sourceRecord.data));
-        const targetDataStr = JSON.stringify(this._normalizeForComparison(targetRecord.data));
-
-        if (sourceDataStr !== targetDataStr) {
-          different.push({
-            path,
-            source: sourceRecord.data,
-            target: targetRecord.data,
-          });
-        }
-      }
-    }
-
-    // Check for extra records in target
-    for (const path of targetMap.keys()) {
-      if (!sourceMap.has(path)) {
-        extra.push(path);
-      }
-    }
-
-    const valid = missing.length === 0 && different.length === 0;
-
-    console.log(`Validation ${valid ? 'PASSED' : 'FAILED'}:`);
-    console.log(`  Source records: ${sourceData.length}`);
-    console.log(`  Target records: ${targetData.length}`);
-    console.log(`  Missing: ${missing.length}`);
-    console.log(`  Different: ${different.length}`);
-    console.log(`  Extra: ${extra.length}`);
-
-    return {
-      valid,
-      sourceCount: sourceData.length,
-      targetCount: targetData.length,
-      missing,
-      different,
-      extra,
-    };
-  }
-
-  /**
-   * Normalize data for comparison (remove volatile metadata)
-   * @private
-   */
-  _normalizeForComparison(data) {
-    if (!data || typeof data !== 'object') return data;
-
-    const normalized = { ...data };
-
-    // Remove metadata that may legitimately differ
-    delete normalized._meta;
-    delete normalized._author;
-    delete normalized._timestamp;
-
-    return normalized;
-  }
-
-  /**
-   * Export bundle to JSON file (for manual transfer)
-   * @param {DataBundle} bundle - Data bundle
-   * @param {string} filePath - Output file path
-   */
-  async exportToFile(bundle, filePath) {
-    const fs = await import('fs/promises');
-    await fs.writeFile(filePath, JSON.stringify(bundle, null, 2), 'utf-8');
-    console.log(`Bundle exported to ${filePath}`);
-  }
-
-  /**
-   * Import bundle from JSON file
-   * @param {string} filePath - Input file path
-   * @returns {Promise<DataBundle>} Loaded bundle
-   */
-  async importFromFile(filePath) {
-    const fs = await import('fs/promises');
-    const content = await fs.readFile(filePath, 'utf-8');
-    const bundle = JSON.parse(content);
-    console.log(`Bundle loaded from ${filePath}: ${bundle.recordCount} records`);
-    return bundle;
-  }
-
-  /**
-   * Close all backend connections
-   */
-  close() {
-    if (this.sourceBackend) {
-      this.sourceBackend.close();
-    }
-    if (this.targetBackend) {
-      this.targetBackend.close();
-    }
-  }
-}
-
-/**
- * Quick migration function for common use cases
- * @param {Object} sourceConfig - Source backend config with 'type' field
- * @param {Object} targetConfig - Target backend config with 'type' field
- * @param {string} [pathPrefix] - Optional path filter
- * @param {Object} [options] - Migration options
- * @returns {Promise<Object>} Migration results
- */
-export async function quickMigrate(sourceConfig, targetConfig, pathPrefix = '', options = {}) {
-  const tool = new MigrationTool();
-
-  try {
-    await tool.setSource(sourceConfig.type, sourceConfig);
-    await tool.setTarget(targetConfig.type, targetConfig);
-
-    const results = await tool.migrate(pathPrefix, options);
-
-    if (!options.skipValidation) {
-      const validation = await tool.validate(pathPrefix);
-      results.validation = validation;
-    }
-
-    return results;
-  } finally {
-    tool.close();
-  }
-}
-
-export default MigrationTool;

package/src/storage/unified-storage.js

@@ -1,161 +0,0 @@
-/**
- * @fileoverview Unified Storage Adapter.
- *
- * Routes storage operations to the correct backend (Nostr or GunDB).
- * Provides a consistent API for reading, writing, updating, and deleting
- * data across different storage backends.
- *
- * @module storage/unified-storage
- */
-
-import * as nostrWrapper from './nostr-wrapper.js';
-import * as gunWrapper from './gun-wrapper.js';
-
-/**
- * Build path from components
- * @param {string} appName - Application namespace
- * @param {string} holonId - Holon identifier
- * @param {string} lensName - Lens name
- * @param {string} [key] - Optional data key
- * @returns {string} Constructed path
- */
-export function buildPath(appName, holonId, lensName, key = null) {
-  // Both backends use the same path format
-  return nostrWrapper.buildPath(appName, holonId, lensName, key);
-}
-
-/**
- * Write data to storage
- * @param {Object} client - Client instance (nostr client or gun-compatible client)
- * @param {string} path - Storage path
- * @param {Object} data - Data to write
- * @param {Object} [options={}] - Write options
- * @returns {Promise<boolean>} Success indicator
- */
-export async function write(client, path, data, options = {}) {
-  // Check if this is a GunDB client with backend methods (preferred - has write cache)
-  if (client.write && client.gun) {
-    return client.write(path, data, options);
-  }
-  // Fallback to direct gunWrapper (no write cache)
-  if (client.gun) {
-    return gunWrapper.write(client.gun, path, data, options);
-  }
-  // Default to Nostr
-  return nostrWrapper.write(client, path, data, options);
-}
-
-/**
- * Read data from storage
- * @param {Object} client - Client instance
- * @param {string} path - Storage path
- * @param {Object} [options] - Read options
- * @returns {Promise<Object|null>} Data or null
- */
-export async function read(client, path, options = {}) {
-  // Check if this is a GunDB client with backend methods (preferred - has write cache)
-  if (client.read && client.gun) {
-    return client.read(path, options);
-  }
-  // Fallback to direct gunWrapper
-  if (client.gun) {
-    return gunWrapper.read(client.gun, path);
-  }
-  return nostrWrapper.read(client, path, options);
-}
-
-/**
- * Read all data under a path prefix
- * @param {Object} client - Client instance
- * @param {string} path - Path prefix
- * @param {Object} [options] - Query options
- * @returns {Promise<Object[]>} Array of data objects
- */
-export async function readAll(client, path, options = {}) {
-  // Check if this is a GunDB client with backend methods (preferred - has write cache)
-  if (client.readAll && client.gun) {
-    return client.readAll(path, options);
-  }
-  // Fallback to direct gunWrapper
-  if (client.gun) {
-    return gunWrapper.readAll(client.gun, path);
-  }
-  return nostrWrapper.readAll(client, path, options);
-}
-
-/**
- * Update data (merge fields)
- * @param {Object} client - Client instance
- * @param {string} path - Storage path
- * @param {Object} updates - Fields to update
- * @returns {Promise<boolean>} Success indicator
- */
-export async function update(client, path, updates) {
-  // Check if this is a GunDB client with backend methods (preferred - has write cache)
-  if (client.update && client.gun) {
-    return client.update(path, updates);
-  }
-  // Fallback to direct gunWrapper
-  if (client.gun) {
-    return gunWrapper.update(client.gun, path, updates);
-  }
-  return nostrWrapper.update(client, path, updates);
-}
-
-/**
- * Delete data at path
- * @param {Object} client - Client instance
- * @param {string} path - Storage path
- * @param {Object} [options] - Delete options
- * @param {string} [options.signingKey] - Private key for signing tombstones (hex format)
- * @param {string} [options.authorPubkey] - Public key of the data author
- * @returns {Promise<boolean>} Success indicator
- */
-export async function deleteData(client, path, options = {}) {
-  // Check if this is a GunDB client with backend methods (preferred - has write cache)
-  if (client.delete && client.gun) {
-    return client.delete(path);
-  }
-  // Fallback to direct gunWrapper
-  if (client.gun) {
-    return gunWrapper.deleteData(client.gun, path);
-  }
-  return nostrWrapper.deleteData(client, path, options);
-}
-
-/**
- * Delete all data under path prefix
- * @param {Object} client - Client instance
- * @param {string} path - Path prefix
- * @param {Object} [options] - Delete options
- * @param {string} [options.signingKey] - Private key for signing tombstones (hex format)
- * @param {string} [options.authorPubkey] - Public key of the data author
- * @returns {Promise<Object>} Deletion results
- */
-export async function deleteAll(client, path, options = {}) {
-  // Fallback to direct gunWrapper (deleteAll not typically in client interface)
-  if (client.gun) {
-    return gunWrapper.deleteAll(client.gun, path);
-  }
-  return nostrWrapper.deleteAll(client, path, options);
-}
-
-/**
- * Subscribe to data changes
- * @param {Object} client - Client instance
- * @param {string} path - Path or path prefix
- * @param {Function} callback - Called on changes
- * @param {Object} [options] - Subscription options
- * @returns {Object} Subscription with unsubscribe method
- */
-export function subscribe(client, path, callback, options = {}) {
-  // Check if this is a GunDB client with backend methods
-  if (client.subscribe && client.gun) {
-    return client.subscribe(path, callback, options);
-  }
-  // Fallback to direct gunWrapper
-  if (client.gun) {
-    return gunWrapper.subscribe(client.gun, path, callback, options);
-  }
-  return nostrWrapper.subscribe(client, path, callback, options);
-}