holosphere 1.1.20 → 2.0.0-alpha1

package/scripts/read-example.js

@@ -0,0 +1,186 @@
+#!/usr/bin/env node
+
+/**
+ * Example script to read imported data from holosphere
+ *
+ * Demonstrates various ways to query and retrieve data
+ */
+
+import { HoloSphere } from '../src/index.js';
+
+async function main() {
+  console.log('HoloSphere Read Example');
+  console.log('======================\n');
+
+  // Initialize holosphere with the same app name used during import
+  // Using relay.holons.io for distributed access
+  const hs = new HoloSphere({
+    appName: 'imported',
+    relays: ['wss://relay.holons.io'],
+    persistence: true,
+    logLevel: 'INFO'
+  });
+
+  console.log('Holosphere initialized with relay.holons.io\n');
+
+  // Wait for storage to be ready and loaded
+  console.log('Loading data from persistent storage and relay...');
+  await new Promise(resolve => setTimeout(resolve, 2000));
+
+  // Example 1: Read all data from a specific lens
+  console.log('Example 1: Reading all quests from demo app');
+  console.log('='.repeat(50));
+  try {
+    const quests = await hs.readGlobal('quests');
+    if (quests && typeof quests === 'object') {
+      const questArray = Object.values(quests);
+      console.log(`Found ${questArray.length} quests:`);
+
+      // Show first 3 quests
+      questArray.slice(0, 3).forEach((quest, idx) => {
+        console.log(`\n${idx + 1}. Quest ID: ${quest.id}`);
+        console.log(`   Title: ${quest.title || 'N/A'}`);
+        console.log(`   Status: ${quest.status || 'N/A'}`);
+        console.log(`   Type: ${quest.type || 'N/A'}`);
+      });
+
+      if (questArray.length > 3) {
+        console.log(`\n... and ${questArray.length - 3} more quests`);
+      }
+    } else {
+      console.log('No quests found or data format unexpected');
+    }
+  } catch (error) {
+    console.error('Error reading quests:', error.message);
+  }
+
+  // Example 2: Read a specific item by ID
+  console.log('\n\nExample 2: Reading a specific quest by ID');
+  console.log('='.repeat(50));
+  try {
+    const questId = '1734348140557x6irmp8vm';
+    const quest = await hs.readGlobal('quests', questId);
+
+    if (quest) {
+      console.log(`Quest found:`);
+      console.log(JSON.stringify(quest, null, 2));
+    } else {
+      console.log(`Quest with ID ${questId} not found`);
+    }
+  } catch (error) {
+    console.error('Error reading specific quest:', error.message);
+  }
+
+  // Example 3: Read all checklists
+  console.log('\n\nExample 3: Reading all checklists');
+  console.log('='.repeat(50));
+  try {
+    const checklists = await hs.readGlobal('checklists');
+
+    if (checklists && typeof checklists === 'object') {
+      const checklistArray = Object.values(checklists);
+      console.log(`Found ${checklistArray.length} checklists:`);
+
+      checklistArray.slice(0, 5).forEach((checklist, idx) => {
+        console.log(`\n${idx + 1}. ${checklist.id}`);
+        if (checklist.value) {
+          console.log(`   Value: ${JSON.stringify(checklist.value).substring(0, 100)}...`);
+        }
+      });
+    } else {
+      console.log('No checklists found');
+    }
+  } catch (error) {
+    console.error('Error reading checklists:', error.message);
+  }
+
+  // Example 4: Read settings data
+  console.log('\n\nExample 4: Reading settings');
+  console.log('='.repeat(50));
+  try {
+    const settings = await hs.readGlobal('settings');
+
+    if (settings && typeof settings === 'object') {
+      const settingsArray = Object.values(settings);
+      console.log(`Found ${settingsArray.length} settings entries:`);
+
+      settingsArray.slice(0, 3).forEach((setting, idx) => {
+        console.log(`\n${idx + 1}. Setting ID: ${setting.id}`);
+        console.log(`   Data:`, JSON.stringify(setting, null, 2).substring(0, 200));
+      });
+    } else {
+      console.log('No settings found');
+    }
+  } catch (error) {
+    console.error('Error reading settings:', error.message);
+  }
+
+  // Example 5: Read from H3 holon (if any exist)
+  console.log('\n\nExample 5: Reading from H3 holons');
+  console.log('='.repeat(50));
+  try {
+    const h3HolonId = '881e850d53fffff';
+    const hubs = await hs.read(h3HolonId, 'hubs');
+
+    if (hubs && typeof hubs === 'object') {
+      const hubsArray = Object.values(hubs);
+      console.log(`Found ${hubsArray.length} hubs in holon ${h3HolonId}:`);
+
+      hubsArray.forEach((hub, idx) => {
+        console.log(`\n${idx + 1}. Hub ID: ${hub.id}`);
+        console.log(`   Data:`, JSON.stringify(hub, null, 2));
+      });
+    } else {
+      console.log(`No hubs found in holon ${h3HolonId}`);
+    }
+  } catch (error) {
+    console.error('Error reading from H3 holon:', error.message);
+  }
+
+  // Example 6: Browse available lenses
+  console.log('\n\nExample 6: Available lenses (data categories)');
+  console.log('='.repeat(50));
+
+  const sampleLenses = [
+    'quests', 'checklists', 'settings', 'users', 'shopping',
+    'expenses', 'chats', 'announcements', 'federation', 'hubs'
+  ];
+
+  console.log('Sample lenses available in the imported data:');
+  sampleLenses.forEach((lens, idx) => {
+    console.log(`${idx + 1}. ${lens}`);
+  });
+
+  console.log('\nTo read from any lens, use:');
+  console.log('  await hs.readGlobal(lensName)           // Get all items');
+  console.log('  await hs.readGlobal(lensName, itemId)   // Get specific item');
+
+  // Example 7: Summary statistics
+  console.log('\n\nExample 7: Data summary');
+  console.log('='.repeat(50));
+
+  const lensesToCheck = ['quests', 'checklists', 'settings', 'users', 'shopping'];
+
+  for (const lens of lensesToCheck) {
+    try {
+      const data = await hs.readGlobal(lens);
+      if (data && typeof data === 'object') {
+        const count = Object.keys(data).length;
+        console.log(`${lens}: ${count} items`);
+      }
+    } catch (error) {
+      console.log(`${lens}: Error reading (${error.message})`);
+    }
+  }
+
+  // Show holosphere metrics
+  console.log('\n\nHolosphere Metrics:');
+  console.log('='.repeat(50));
+  console.log(JSON.stringify(hs.metrics(), null, 2));
+}
+
+// Run the example
+main().catch(error => {
+  console.error('Fatal error:', error);
+  process.exit(1);
+});

package/scripts/relay-diagnostic.js

@@ -0,0 +1,59 @@
+#!/usr/bin/env node
+
+/**
+ * Diagnostic script to test relay connectivity and write operations
+ */
+
+import { HoloSphere } from '../src/index.js';
+import dotenv from 'dotenv';
+
+// Load environment variables
+dotenv.config();
+
+async function main() {
+  console.log('Relay Diagnostic Test');
+  console.log('=====================\n');
+
+  const hs = new HoloSphere({
+    appName: 'test',
+    relays: ['wss://relay.holons.io'],
+    persistence: true,
+    logLevel: 'DEBUG',
+    privateKey: process.env.HOLOSPHERE_PRIVATE_KEY
+  });
+
+  console.log('Testing write operation...\n');
+
+  const testData = {
+    id: 'test-1',
+    message: 'Hello from HoloSphere!',
+    timestamp: Date.now()
+  };
+
+  try {
+    console.log('Writing data:', JSON.stringify(testData, null, 2));
+    testData.id = 'test-1';
+    const result = await hs.writeGlobal('test', testData);
+    console.log('\nWrite result:', result);
+
+    if (result) {
+      console.log('✓ Write succeeded');
+
+      console.log('\nWaiting 3 seconds...');
+      await new Promise(resolve => setTimeout(resolve, 3000));
+
+      console.log('\nReading data back...');
+      const retrieved = await hs.readGlobal('test', 'test-1');
+      console.log('Retrieved:', JSON.stringify(retrieved, null, 2));
+    } else {
+      console.log('✗ Write failed');
+    }
+  } catch (error) {
+    console.error('Error:', error);
+    console.error('Stack:', error.stack);
+  }
+
+  console.log('\nMetrics:', hs.metrics());
+}
+
+main().catch(console.error);

package/scripts/relay-example.js

@@ -0,0 +1,179 @@
+#!/usr/bin/env node
+
+/**
+ * Example: Write quests to Nostr relays and read them back
+ *
+ * This demonstrates the full relay round-trip:
+ * 1. Write data to distributed Nostr relays
+ * 2. Wait for propagation
+ * 3. Read data back from relays
+ * 4. Display results
+ */
+
+import { HoloSphere } from '../src/index.js';
+import dotenv from 'dotenv';
+
+// Load environment variables
+dotenv.config();
+
+async function main() {
+  console.log('HoloSphere Relay Example');
+  console.log('========================\n');
+
+  // Initialize holosphere with actual Nostr relays
+  const hs = new HoloSphere({
+    appName: 'relay-demo',
+    relays: [
+      'wss://relay.holons.io',
+      'wss://relay.nostr.band',
+      'wss://nos.lol'
+    ],
+    persistence: true,
+    logLevel: 'INFO',
+    privateKey: process.env.HOLOSPHERE_PRIVATE_KEY
+  });
+
+  console.log('✓ HoloSphere initialized with Nostr relays\n');
+
+  // Sample quests to write
+  const quests = [
+    {
+      id: 'quest-1',
+      title: 'Build distributed task manager',
+      description: 'Create a P2P task management system using Nostr',
+      status: 'in-progress',
+      type: 'project',
+      priority: 'high',
+      created: new Date().toISOString(),
+      tags: ['nostr', 'p2p', 'tasks']
+    },
+    {
+      id: 'quest-2',
+      title: 'Test relay connectivity',
+      description: 'Verify that data can be written and read from Nostr relays',
+      status: 'completed',
+      type: 'task',
+      priority: 'high',
+      created: new Date().toISOString(),
+      tags: ['testing', 'nostr']
+    },
+    {
+      id: 'quest-3',
+      title: 'Implement geospatial queries',
+      description: 'Add support for querying tasks by location using H3',
+      status: 'planned',
+      type: 'feature',
+      priority: 'medium',
+      created: new Date().toISOString(),
+      tags: ['h3', 'spatial', 'queries']
+    }
+  ];
+
+  // Step 1: Write quests to relays
+  console.log('Step 1: Writing quests to Nostr relays');
+  console.log('='.repeat(50));
+
+  for (const quest of quests) {
+    try {
+      const success = await hs.writeGlobal('quests', quest);
+      if (success) {
+        console.log(`✓ Written: "${quest.title}" (${quest.id})`);
+      } else {
+        console.log(`✗ Failed to write: "${quest.title}"`);
+      }
+    } catch (error) {
+      console.error(`✗ Error writing ${quest.id}:`, error.message);
+    }
+  }
+
+  console.log('\n');
+
+  // Step 2: Wait for relay propagation
+  console.log('Step 2: Waiting for relay propagation...');
+  console.log('='.repeat(50));
+  const waitTime = 3;
+  for (let i = waitTime; i > 0; i--) {
+    process.stdout.write(`\rWaiting ${i} seconds... `);
+    await new Promise(resolve => setTimeout(resolve, 1000));
+  }
+  console.log('\r✓ Wait complete                \n');
+
+  // Step 3: Read quests back from relays
+  console.log('Step 3: Reading quests from Nostr relays');
+  console.log('='.repeat(50));
+
+  // Read individual quests
+  console.log('\nReading individual quests by ID:\n');
+
+  for (const quest of quests) {
+    try {
+      const retrieved = await hs.readGlobal('quests', quest.id);
+
+      if (retrieved) {
+        console.log(`✓ Quest: ${retrieved.title}`);
+        console.log(`  ID: ${retrieved.id}`);
+        console.log(`  Status: ${retrieved.status}`);
+        console.log(`  Priority: ${retrieved.priority}`);
+        console.log(`  Tags: ${retrieved.tags.join(', ')}`);
+        console.log('');
+      } else {
+        console.log(`✗ Quest ${quest.id} not found`);
+        console.log('');
+      }
+    } catch (error) {
+      console.error(`✗ Error reading ${quest.id}:`, error.message);
+      console.log('');
+    }
+  }
+
+  // Read all quests from the lens
+  console.log('Reading all quests from the lens:\n');
+
+  try {
+    const allQuests = await hs.readGlobal('quests');
+
+    if (allQuests && typeof allQuests === 'object') {
+      const questArray = Object.values(allQuests);
+      console.log(`✓ Found ${questArray.length} total quests in relay-demo/global/quests:`);
+      console.log('');
+
+      questArray.forEach((q, idx) => {
+        console.log(`${idx + 1}. ${q.title} (${q.status})`);
+        if (q.description) {
+          console.log(`   ${q.description.substring(0, 60)}...`);
+        }
+      });
+    } else {
+      console.log('✗ No quests found or unexpected data format');
+    }
+  } catch (error) {
+    console.error('✗ Error reading all quests:', error.message);
+  }
+
+  console.log('\n');
+
+  // Step 4: Summary and metrics
+  console.log('Step 4: Summary');
+  console.log('='.repeat(50));
+
+  const metrics = hs.metrics();
+  console.log('Operation Metrics:');
+  console.log(`  Writes: ${metrics.writes}`);
+  console.log(`  Reads: ${metrics.reads}`);
+  console.log(`  Average write time: ${metrics.avgWriteTime || 0}ms`);
+  console.log(`  Average read time: ${metrics.avgReadTime || 0}ms`);
+
+  console.log('\n✓ Relay example complete!\n');
+
+  console.log('Key Takeaways:');
+  console.log('- Data is written to multiple Nostr relays for redundancy');
+  console.log('- Reads query relays and return the most recent version');
+  console.log('- Local cache provides fast access after initial fetch');
+  console.log('- All data is cryptographically signed and verifiable');
+}
+
+// Run the example
+main().catch(error => {
+  console.error('\n✗ Fatal error:', error);
+  process.exit(1);
+});

package/scripts/resync-to-relay.js

@@ -0,0 +1,245 @@
+#!/usr/bin/env node
+
+/**
+ * Re-sync missing data to relay with retry logic and rate limiting
+ *
+ * This script:
+ * 1. Compares local storage vs relay
+ * 2. Identifies missing items
+ * 3. Re-publishes with retry logic and rate limiting
+ * 4. Reports success/failure for each item
+ */
+
+import { HoloSphere } from '../src/index.js';
+import dotenv from 'dotenv';
+
+dotenv.config();
+
+// Parse command line arguments for configuration
+const args = process.argv.slice(2);
+let relayUrl = 'wss://relay.holons.io'; // Default relay
+let holonId = '235114395'; // Default holon
+
+for (let i = 0; i < args.length; i++) {
+  if (args[i] === '--relay' && args[i + 1]) {
+    relayUrl = args[i + 1];
+    i++;
+  } else if (args[i] === '--holon' && args[i + 1]) {
+    holonId = args[i + 1];
+    i++;
+  }
+}
+
+// Configuration
+const CONFIG = {
+  holonId,
+  relays: [relayUrl],
+  batchSize: 10,           // Process 10 items at a time
+  delayBetweenItems: 200,  // 200ms between each publish
+  delayBetweenBatches: 2000, // 2s between batches
+  maxRetries: 3,            // Retry failed publishes 3 times
+  retryDelay: 1000,         // 1s between retries
+};
+
+class SyncStats {
+  constructor() {
+    this.total = 0;
+    this.synced = 0;
+    this.failed = 0;
+    this.skipped = 0;
+    this.failures = [];
+  }
+
+  report() {
+    console.log('\n' + '='.repeat(60));
+    console.log('Sync Complete');
+    console.log('='.repeat(60));
+    console.log(`Total items:    ${this.total}`);
+    console.log(`Synced:         ${this.synced} ✓`);
+    console.log(`Failed:         ${this.failed} ✗`);
+    console.log(`Skipped:        ${this.skipped}`);
+    console.log(`Success rate:   ${((this.synced / this.total) * 100).toFixed(1)}%`);
+
+    if (this.failures.length > 0) {
+      console.log('\nFailed items:');
+      this.failures.forEach(({ lens, id, error }) => {
+        console.log(`  - ${lens}/${id}: ${error}`);
+      });
+    }
+  }
+}
+
+async function sleep(ms) {
+  return new Promise(resolve => setTimeout(resolve, ms));
+}
+
+async function publishWithRetry(hs, holonId, lens, item, stats, retries = 0) {
+  try {
+    const itemId = item.id || `unknown-${Date.now()}`;
+
+    // Attempt to write
+    const success = await hs.write(holonId, lens, item);
+
+    if (success) {
+      stats.synced++;
+      return true;
+    } else {
+      throw new Error('Write returned false');
+    }
+  } catch (error) {
+    if (retries < CONFIG.maxRetries) {
+      console.log(`  Retry ${retries + 1}/${CONFIG.maxRetries} for ${lens}/${item.id}`);
+      await sleep(CONFIG.retryDelay);
+      return publishWithRetry(hs, holonId, lens, item, stats, retries + 1);
+    } else {
+      stats.failed++;
+      stats.failures.push({
+        lens,
+        id: item.id || 'unknown',
+        error: error.message
+      });
+      return false;
+    }
+  }
+}
+
+async function syncLens(hsLocal, hsRelay, holonId, lens, stats) {
+  console.log(`\nSyncing lens: ${lens}`);
+  console.log('-'.repeat(60));
+
+  // Get data from both sources
+  const localData = await hsLocal.read(holonId, lens);
+  const relayData = await hsRelay.read(holonId, lens);
+
+  if (!localData || localData.length === 0) {
+    console.log(`  No local data for ${lens}`);
+    return;
+  }
+
+  // Convert to maps for comparison
+  const localMap = new Map();
+  localData.forEach(item => {
+    if (item && item.id) {
+      localMap.set(item.id.toString(), item);
+    }
+  });
+
+  const relayMap = new Map();
+  if (relayData && relayData.length > 0) {
+    relayData.forEach(item => {
+      if (item && item.id) {
+        relayMap.set(item.id.toString(), item);
+      }
+    });
+  }
+
+  // Find missing items
+  const missing = [];
+  for (const [id, item] of localMap) {
+    if (!relayMap.has(id)) {
+      missing.push(item);
+    }
+  }
+
+  console.log(`  Local:   ${localMap.size} items`);
+  console.log(`  Relay:   ${relayMap.size} items`);
+  console.log(`  Missing: ${missing.length} items`);
+
+  if (missing.length === 0) {
+    console.log(`  ✓ All items synced`);
+    return;
+  }
+
+  stats.total += missing.length;
+
+  // Publish in batches
+  const batches = [];
+  for (let i = 0; i < missing.length; i += CONFIG.batchSize) {
+    batches.push(missing.slice(i, i + CONFIG.batchSize));
+  }
+
+  console.log(`  Publishing in ${batches.length} batches...`);
+
+  for (let batchNum = 0; batchNum < batches.length; batchNum++) {
+    const batch = batches[batchNum];
+    console.log(`  Batch ${batchNum + 1}/${batches.length} (${batch.length} items)`);
+
+    for (const item of batch) {
+      const itemId = item.id || 'unknown';
+      process.stdout.write(`    ${lens}/${itemId}... `);
+
+      const success = await publishWithRetry(hsRelay, holonId, lens, item, stats);
+
+      if (success) {
+        console.log('✓');
+      } else {
+        console.log('✗');
+      }
+
+      // Rate limiting between items
+      await sleep(CONFIG.delayBetweenItems);
+    }
+
+    // Longer delay between batches
+    if (batchNum < batches.length - 1) {
+      console.log(`  Waiting ${CONFIG.delayBetweenBatches}ms before next batch...`);
+      await sleep(CONFIG.delayBetweenBatches);
+    }
+  }
+}
+
+async function main() {
+  console.log('HoloSphere Relay Re-sync Tool');
+  console.log('=============================\n');
+  console.log(`Holon ID: ${CONFIG.holonId}`);
+  console.log(`Relays:   ${CONFIG.relays.join(', ')}`);
+  console.log(`Batch size: ${CONFIG.batchSize} items`);
+  console.log(`Rate limit: ${CONFIG.delayBetweenItems}ms between items\n`);
+
+  const stats = new SyncStats();
+
+  // Initialize local client (no relays)
+  console.log('Initializing local storage client...');
+  const hsLocal = new HoloSphere({
+    appName: 'Holons',
+    relays: [],
+    persistence: true,
+    logLevel: 'ERROR',
+    privateKey: process.env.HOLOSPHERE_PRIVATE_KEY
+  });
+
+  await sleep(2000);
+  console.log('✓ Local storage loaded\n');
+
+  // Initialize relay client
+  console.log('Initializing relay client...');
+  const hsRelay = new HoloSphere({
+    appName: 'Holons',
+    relays: CONFIG.relays,
+    persistence: false,
+    logLevel: 'ERROR',
+    privateKey: process.env.HOLOSPHERE_PRIVATE_KEY
+  });
+
+  await sleep(2000);
+  console.log('✓ Connected to relay\n');
+
+  // Sync each lens
+  const lenses = ['3891', 'announcements', 'checklists', 'expenses', 'linked_quests',
+                  'profile', 'quests', 'roles', 'settings', 'users'];
+
+  for (const lens of lenses) {
+    await syncLens(hsLocal, hsRelay, CONFIG.holonId, lens, stats);
+  }
+
+  // Report results
+  stats.report();
+
+  console.log('\n✓ Re-sync complete\n');
+  process.exit(0);
+}
+
+main().catch(error => {
+  console.error('\nFatal error:', error);
+  process.exit(1);
+});