@girardmedia/bootspring 1.2.0 → 2.0.3

package/core/r2-sync.js

@@ -0,0 +1,583 @@
+/**
+ * Bootspring Cloud Context Sync (Cloudflare R2)
+ * Sync project context to cloud storage for backup and cross-device access
+ *
+ * @package bootspring
+ * @module core/r2-sync
+ */
+
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+const zlib = require('zlib');
+const utils = require('./utils');
+const projectState = require('./project-state');
+
+// ============================================================================
+// Constants
+// ============================================================================
+
+const SYNC_VERSION = '1.0.0';
+
+// Files and directories to sync
+const SYNC_MANIFEST = {
+  files: [
+    'CLAUDE.md',
+    'todo.md'
+  ],
+  directories: [
+    '.bootspring',
+    'planning'
+  ],
+  exclude: [
+    'node_modules',
+    '.git',
+    '*.log',
+    '.bootspring/logs/*',
+    '.bootspring/telemetry/*'
+  ]
+};
+
+// R2 path structure
+const R2_PATHS = {
+  latest: (projectId) => `projects/${projectId}/latest/`,
+  versions: (projectId) => `projects/${projectId}/versions/`,
+  metadata: (projectId) => `projects/${projectId}/metadata.json`
+};
+
+// ============================================================================
+// R2 Client Management
+// ============================================================================
+
+let r2Client = null;
+
+/**
+ * Get R2 configuration from environment or config
+ * @returns {object|null} R2 configuration or null if not configured
+ */
+function getR2Config() {
+  const config = {
+    accountId: process.env.BOOTSPRING_R2_ACCOUNT_ID,
+    accessKeyId: process.env.BOOTSPRING_R2_ACCESS_KEY_ID,
+    secretAccessKey: process.env.BOOTSPRING_R2_SECRET_ACCESS_KEY,
+    bucketName: process.env.BOOTSPRING_R2_BUCKET_NAME || 'bootspring-context',
+    region: process.env.BOOTSPRING_R2_REGION || 'auto'
+  };
+
+  // Check if essential credentials are present
+  if (!config.accountId || !config.accessKeyId || !config.secretAccessKey) {
+    return null;
+  }
+
+  return config;
+}
+
+/**
+ * Initialize R2 client (lazy loading)
+ * @returns {object|null} S3-compatible client or null
+ */
+function getR2Client() {
+  if (r2Client) return r2Client;
+
+  const config = getR2Config();
+  if (!config) return null;
+
+  try {
+    // Use AWS SDK S3 client (R2 is S3-compatible)
+    const { S3Client } = require('@aws-sdk/client-s3');
+
+    r2Client = new S3Client({
+      region: config.region,
+      endpoint: `https://${config.accountId}.r2.cloudflarestorage.com`,
+      credentials: {
+        accessKeyId: config.accessKeyId,
+        secretAccessKey: config.secretAccessKey
+      }
+    });
+
+    return r2Client;
+  } catch (error) {
+    utils.print.debug(`R2 client initialization failed: ${error.message}`);
+    return null;
+  }
+}
+
+/**
+ * Check if R2 is configured
+ * @returns {boolean} True if R2 credentials are configured
+ */
+function isConfigured() {
+  return getR2Config() !== null;
+}
+
+/**
+ * Validate R2 credentials by testing connection
+ * @returns {Promise<{valid: boolean, error?: string}>}
+ */
+async function validateCredentials() {
+  const client = getR2Client();
+  if (!client) {
+    return { valid: false, error: 'R2 credentials not configured' };
+  }
+
+  try {
+    const { HeadBucketCommand } = require('@aws-sdk/client-s3');
+    const config = getR2Config();
+
+    await client.send(new HeadBucketCommand({ Bucket: config.bucketName }));
+    return { valid: true };
+  } catch (error) {
+    if (error.name === 'NotFound') {
+      return { valid: false, error: `Bucket '${getR2Config().bucketName}' not found` };
+    }
+    return { valid: false, error: error.message };
+  }
+}
+
+// ============================================================================
+// Context Package Management
+// ============================================================================
+
+/**
+ * Generate a context package from project files
+ * @param {string} projectRoot - Project root directory
+ * @returns {object} Context package with files and metadata
+ */
+function generateContextPackage(projectRoot) {
+  const pkg = {
+    version: SYNC_VERSION,
+    createdAt: new Date().toISOString(),
+    projectRoot: projectRoot,
+    files: {},
+    metadata: {
+      totalFiles: 0,
+      totalSize: 0,
+      checksum: null
+    }
+  };
+
+  // Collect files
+  for (const file of SYNC_MANIFEST.files) {
+    const filePath = path.join(projectRoot, file);
+    if (fs.existsSync(filePath)) {
+      const content = fs.readFileSync(filePath, 'utf-8');
+      pkg.files[file] = {
+        content,
+        size: Buffer.byteLength(content),
+        mtime: fs.statSync(filePath).mtime.toISOString()
+      };
+      pkg.metadata.totalFiles++;
+      pkg.metadata.totalSize += Buffer.byteLength(content);
+    }
+  }
+
+  // Collect directories
+  for (const dir of SYNC_MANIFEST.directories) {
+    const dirPath = path.join(projectRoot, dir);
+    if (fs.existsSync(dirPath) && fs.statSync(dirPath).isDirectory()) {
+      collectDirectoryFiles(dirPath, dir, pkg, projectRoot);
+    }
+  }
+
+  // Generate checksum
+  const contentHash = crypto.createHash('sha256');
+  for (const [filePath, fileData] of Object.entries(pkg.files)) {
+    contentHash.update(`${filePath}:${fileData.content}`);
+  }
+  pkg.metadata.checksum = contentHash.digest('hex');
+
+  return pkg;
+}
+
+/**
+ * Recursively collect files from a directory
+ * @param {string} dirPath - Directory path
+ * @param {string} relativePath - Relative path for storage
+ * @param {object} pkg - Package to add files to
+ * @param {string} projectRoot - Project root
+ */
+function collectDirectoryFiles(dirPath, relativePath, pkg, projectRoot) {
+  try {
+    const items = fs.readdirSync(dirPath, { withFileTypes: true });
+
+    for (const item of items) {
+      const fullPath = path.join(dirPath, item.name);
+      const itemRelativePath = path.join(relativePath, item.name);
+
+      // Check exclusions
+      if (shouldExclude(itemRelativePath)) continue;
+
+      if (item.isDirectory()) {
+        collectDirectoryFiles(fullPath, itemRelativePath, pkg, projectRoot);
+      } else if (item.isFile()) {
+        try {
+          const content = fs.readFileSync(fullPath, 'utf-8');
+          pkg.files[itemRelativePath] = {
+            content,
+            size: Buffer.byteLength(content),
+            mtime: fs.statSync(fullPath).mtime.toISOString()
+          };
+          pkg.metadata.totalFiles++;
+          pkg.metadata.totalSize += Buffer.byteLength(content);
+        } catch (_e) {
+          // Skip binary or unreadable files
+        }
+      }
+    }
+  } catch (_e) {
+    // Skip inaccessible directories
+  }
+}
+
+/**
+ * Check if a path should be excluded from sync
+ * @param {string} relativePath - Relative path to check
+ * @returns {boolean} True if should be excluded
+ */
+function shouldExclude(relativePath) {
+  for (const pattern of SYNC_MANIFEST.exclude) {
+    if (pattern.includes('*')) {
+      const regex = new RegExp(pattern.replace(/\*/g, '.*'));
+      if (regex.test(relativePath)) return true;
+    } else if (relativePath === pattern || relativePath.startsWith(pattern + '/')) {
+      return true;
+    }
+  }
+  return false;
+}
+
+/**
+ * Compress context package
+ * @param {object} pkg - Context package
+ * @returns {Buffer} Compressed data
+ */
+function compressPackage(pkg) {
+  const json = JSON.stringify(pkg);
+  return zlib.gzipSync(json);
+}
+
+/**
+ * Decompress context package
+ * @param {Buffer} data - Compressed data
+ * @returns {object} Context package
+ */
+function decompressPackage(data) {
+  const json = zlib.gunzipSync(data).toString('utf-8');
+  return JSON.parse(json);
+}
+
+// ============================================================================
+// Sync Operations
+// ============================================================================
+
+/**
+ * Push context to R2
+ * @param {string} projectRoot - Project root directory
+ * @param {string} projectId - Project ID
+ * @param {object} options - Options
+ * @returns {Promise<{success: boolean, version?: string, error?: string}>}
+ */
+async function pushContext(projectRoot, projectId, options = {}) {
+  const client = getR2Client();
+  if (!client) {
+    return { success: false, error: 'R2 not configured' };
+  }
+
+  try {
+    const { PutObjectCommand } = require('@aws-sdk/client-s3');
+    const config = getR2Config();
+
+    // Generate context package
+    const pkg = generateContextPackage(projectRoot);
+    const compressed = compressPackage(pkg);
+    const version = `v${Date.now()}`;
+
+    // Upload to latest
+    await client.send(new PutObjectCommand({
+      Bucket: config.bucketName,
+      Key: `${R2_PATHS.latest(projectId)}context.gz`,
+      Body: compressed,
+      ContentType: 'application/gzip',
+      Metadata: {
+        version: version,
+        checksum: pkg.metadata.checksum,
+        fileCount: String(pkg.metadata.totalFiles),
+        syncVersion: SYNC_VERSION
+      }
+    }));
+
+    // Upload version backup if versioning enabled
+    if (options.createVersion !== false) {
+      await client.send(new PutObjectCommand({
+        Bucket: config.bucketName,
+        Key: `${R2_PATHS.versions(projectId)}${version}/context.gz`,
+        Body: compressed,
+        ContentType: 'application/gzip'
+      }));
+    }
+
+    // Update metadata
+    const metadata = {
+      lastPush: new Date().toISOString(),
+      lastVersion: version,
+      checksum: pkg.metadata.checksum,
+      fileCount: pkg.metadata.totalFiles,
+      totalSize: pkg.metadata.totalSize,
+      syncVersion: SYNC_VERSION
+    };
+
+    await client.send(new PutObjectCommand({
+      Bucket: config.bucketName,
+      Key: R2_PATHS.metadata(projectId),
+      Body: JSON.stringify(metadata, null, 2),
+      ContentType: 'application/json'
+    }));
+
+    // Update local state
+    updateLocalSyncState(projectRoot, {
+      lastPush: metadata.lastPush,
+      lastVersion: version,
+      checksum: pkg.metadata.checksum
+    });
+
+    return {
+      success: true,
+      version,
+      fileCount: pkg.metadata.totalFiles,
+      totalSize: pkg.metadata.totalSize
+    };
+  } catch (error) {
+    return { success: false, error: error.message };
+  }
+}
+
+/**
+ * Pull context from R2
+ * @param {string} projectRoot - Project root directory
+ * @param {string} projectId - Project ID
+ * @param {object} options - Options
+ * @returns {Promise<{success: boolean, version?: string, error?: string}>}
+ */
+async function pullContext(projectRoot, projectId, options = {}) {
+  const client = getR2Client();
+  if (!client) {
+    return { success: false, error: 'R2 not configured' };
+  }
+
+  try {
+    const { GetObjectCommand } = require('@aws-sdk/client-s3');
+    const config = getR2Config();
+
+    // Determine which version to pull
+    const key = options.version
+      ? `${R2_PATHS.versions(projectId)}${options.version}/context.gz`
+      : `${R2_PATHS.latest(projectId)}context.gz`;
+
+    // Download
+    const response = await client.send(new GetObjectCommand({
+      Bucket: config.bucketName,
+      Key: key
+    }));
+
+    // Read stream to buffer
+    const chunks = [];
+    for await (const chunk of response.Body) {
+      chunks.push(chunk);
+    }
+    const data = Buffer.concat(chunks);
+
+    // Decompress
+    const pkg = decompressPackage(data);
+
+    // Verify checksum if requested
+    if (options.verifyChecksum) {
+      const localPkg = generateContextPackage(projectRoot);
+      if (localPkg.metadata.checksum === pkg.metadata.checksum) {
+        return { success: true, message: 'Already up to date', upToDate: true };
+      }
+    }
+
+    // Restore files
+    let restoredCount = 0;
+    for (const [relativePath, fileData] of Object.entries(pkg.files)) {
+      const fullPath = path.join(projectRoot, relativePath);
+      const dir = path.dirname(fullPath);
+
+      // Create directory if needed
+      if (!fs.existsSync(dir)) {
+        fs.mkdirSync(dir, { recursive: true });
+      }
+
+      // Write file
+      fs.writeFileSync(fullPath, fileData.content, 'utf-8');
+      restoredCount++;
+    }
+
+    // Update local state
+    updateLocalSyncState(projectRoot, {
+      lastPull: new Date().toISOString(),
+      lastVersion: response.Metadata?.version || 'unknown',
+      checksum: pkg.metadata.checksum
+    });
+
+    return {
+      success: true,
+      version: response.Metadata?.version,
+      restoredCount,
+      totalSize: pkg.metadata.totalSize
+    };
+  } catch (error) {
+    if (error.name === 'NoSuchKey') {
+      return { success: false, error: 'No remote context found' };
+    }
+    return { success: false, error: error.message };
+  }
+}
+
+/**
+ * Get sync status
+ * @param {string} projectRoot - Project root directory
+ * @param {string} projectId - Project ID
+ * @returns {Promise<object>} Sync status
+ */
+async function getStatus(projectRoot, projectId) {
+  const localState = getLocalSyncState(projectRoot);
+  const status = {
+    configured: isConfigured(),
+    local: localState,
+    remote: null,
+    needsSync: false
+  };
+
+  if (!status.configured) {
+    return status;
+  }
+
+  try {
+    const client = getR2Client();
+    const { GetObjectCommand } = require('@aws-sdk/client-s3');
+    const config = getR2Config();
+
+    const response = await client.send(new GetObjectCommand({
+      Bucket: config.bucketName,
+      Key: R2_PATHS.metadata(projectId)
+    }));
+
+    const chunks = [];
+    for await (const chunk of response.Body) {
+      chunks.push(chunk);
+    }
+    status.remote = JSON.parse(Buffer.concat(chunks).toString('utf-8'));
+
+    // Check if sync needed
+    const localPkg = generateContextPackage(projectRoot);
+    status.local.currentChecksum = localPkg.metadata.checksum;
+    status.needsSync = localPkg.metadata.checksum !== status.remote?.checksum;
+  } catch (error) {
+    if (error.name !== 'NoSuchKey') {
+      status.error = error.message;
+    }
+  }
+
+  return status;
+}
+
+/**
+ * List available versions
+ * @param {string} projectId - Project ID
+ * @returns {Promise<string[]>} List of version IDs
+ */
+async function listVersions(projectId) {
+  const client = getR2Client();
+  if (!client) return [];
+
+  try {
+    const { ListObjectsV2Command } = require('@aws-sdk/client-s3');
+    const config = getR2Config();
+
+    const response = await client.send(new ListObjectsV2Command({
+      Bucket: config.bucketName,
+      Prefix: R2_PATHS.versions(projectId),
+      Delimiter: '/'
+    }));
+
+    return (response.CommonPrefixes || [])
+      .map(p => p.Prefix.split('/').filter(Boolean).pop())
+      .sort()
+      .reverse();
+  } catch (_error) {
+    return [];
+  }
+}
+
+// ============================================================================
+// Local State Management
+// ============================================================================
+
+const SYNC_STATE_FILE = '.bootspring/cloud-sync.json';
+
+/**
+ * Get local sync state
+ * @param {string} projectRoot - Project root
+ * @returns {object} Sync state
+ */
+function getLocalSyncState(projectRoot) {
+  const statePath = path.join(projectRoot, SYNC_STATE_FILE);
+  if (fs.existsSync(statePath)) {
+    try {
+      return JSON.parse(fs.readFileSync(statePath, 'utf-8'));
+    } catch (_e) {
+      return {};
+    }
+  }
+  return {};
+}
+
+/**
+ * Update local sync state
+ * @param {string} projectRoot - Project root
+ * @param {object} updates - Updates to apply
+ */
+function updateLocalSyncState(projectRoot, updates) {
+  const statePath = path.join(projectRoot, SYNC_STATE_FILE);
+  const dir = path.dirname(statePath);
+
+  if (!fs.existsSync(dir)) {
+    fs.mkdirSync(dir, { recursive: true });
+  }
+
+  const current = getLocalSyncState(projectRoot);
+  const updated = { ...current, ...updates, updatedAt: new Date().toISOString() };
+
+  fs.writeFileSync(statePath, JSON.stringify(updated, null, 2));
+}
+
+// ============================================================================
+// Exports
+// ============================================================================
+
+module.exports = {
+  // Configuration
+  isConfigured,
+  getR2Config,
+  validateCredentials,
+
+  // Package management
+  generateContextPackage,
+  compressPackage,
+  decompressPackage,
+
+  // Sync operations
+  pushContext,
+  pullContext,
+  getStatus,
+  listVersions,
+
+  // State management
+  getLocalSyncState,
+  updateLocalSyncState,
+
+  // Constants
+  SYNC_MANIFEST,
+  SYNC_VERSION
+};