@girardmedia/bootspring 2.0.21 → 2.0.23

package/src/core/r2-sync.ts

@@ -0,0 +1,691 @@
+/**
+ * Bootspring Cloud Context Sync (Cloudflare R2)
+ * Sync project context to cloud storage for backup and cross-device access
+ *
+ * @package bootspring
+ * @module core/r2-sync
+ */
+
+import * as fs from 'fs';
+import * as path from 'path';
+import * as crypto from 'crypto';
+import * as zlib from 'zlib';
+import * as utils from './utils';
+import * as projectState from './project-state';
+
+// ============================================================================
+// Types
+// ============================================================================
+
+export interface R2Config {
+  accountId: string;
+  accessKeyId: string;
+  secretAccessKey: string;
+  bucketName: string;
+  region: string;
+}
+
+export interface FileData {
+  content: string;
+  size: number;
+  mtime: string;
+}
+
+export interface PackageMetadata {
+  totalFiles: number;
+  totalSize: number;
+  checksum: string | null;
+}
+
+export interface ContextPackage {
+  version: string;
+  createdAt: string;
+  projectRoot: string;
+  files: Record<string, FileData>;
+  metadata: PackageMetadata;
+}
+
+export interface SyncManifest {
+  files: string[];
+  directories: string[];
+  exclude: string[];
+}
+
+export interface PushResult {
+  success: boolean;
+  version?: string | undefined;
+  fileCount?: number | undefined;
+  totalSize?: number | undefined;
+  error?: string | undefined;
+}
+
+export interface PullResult {
+  success: boolean;
+  version?: string | undefined;
+  restoredCount?: number | undefined;
+  totalSize?: number | undefined;
+  message?: string | undefined;
+  upToDate?: boolean | undefined;
+  error?: string | undefined;
+}
+
+export interface SyncStatus {
+  configured: boolean;
+  local: LocalSyncState;
+  remote: RemoteMetadata | null;
+  needsSync: boolean;
+  error?: string | undefined;
+}
+
+export interface LocalSyncState {
+  lastPush?: string | undefined;
+  lastPull?: string | undefined;
+  lastVersion?: string | undefined;
+  checksum?: string | undefined;
+  currentChecksum?: string | undefined;
+  updatedAt?: string | undefined;
+}
+
+export interface RemoteMetadata {
+  lastPush: string;
+  lastVersion: string;
+  checksum: string;
+  fileCount: number;
+  totalSize: number;
+  syncVersion: string;
+}
+
+export interface CredentialValidationResult {
+  valid: boolean;
+  error?: string | undefined;
+}
+
+export interface PushOptions {
+  createVersion?: boolean | undefined;
+}
+
+export interface PullOptions {
+  version?: string | undefined;
+  verifyChecksum?: boolean | undefined;
+}
+
+// ============================================================================
+// Constants
+// ============================================================================
+
+export const SYNC_VERSION = '1.0.0';
+
+// Files and directories to sync
+export const SYNC_MANIFEST: SyncManifest = {
+  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: string) => `projects/${projectId}/latest/`,
+  versions: (projectId: string) => `projects/${projectId}/versions/`,
+  metadata: (projectId: string) => `projects/${projectId}/metadata.json`
+};
+
+// Local sync state file
+const SYNC_STATE_FILE = '.bootspring/cloud-sync.json';
+
+// ============================================================================
+// R2 Client Management
+// ============================================================================
+
+// Lazy-loaded types
+interface S3Client {
+  send: (command: unknown) => Promise<unknown>;
+}
+
+let r2Client: S3Client | null = null;
+
+/**
+ * Get R2 configuration from environment or config
+ */
+export function getR2Config(): R2Config | null {
+  const accountId = process.env['BOOTSPRING_R2_ACCOUNT_ID'];
+  const accessKeyId = process.env['BOOTSPRING_R2_ACCESS_KEY_ID'];
+  const secretAccessKey = process.env['BOOTSPRING_R2_SECRET_ACCESS_KEY'];
+  const bucketName = process.env['BOOTSPRING_R2_BUCKET_NAME'] || 'bootspring-context';
+  const region = process.env['BOOTSPRING_R2_REGION'] || 'auto';
+
+  // Check if essential credentials are present
+  if (!accountId || !accessKeyId || !secretAccessKey) {
+    return null;
+  }
+
+  return {
+    accountId,
+    accessKeyId,
+    secretAccessKey,
+    bucketName,
+    region
+  };
+}
+
+/**
+ * Initialize R2 client (lazy loading)
+ */
+function getR2Client(): S3Client | null {
+  if (r2Client) return r2Client;
+
+  const config = getR2Config();
+  if (!config) return null;
+
+  try {
+    // Use AWS SDK S3 client (R2 is S3-compatible)
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
+    const { S3Client } = require('@aws-sdk/client-s3') as {
+      S3Client: new (config: unknown) => S3Client;
+    };
+
+    r2Client = new S3Client({
+      region: config.region,
+      endpoint: `https://${config.accountId}.r2.cloudflarestorage.com`,
+      credentials: {
+        accessKeyId: config.accessKeyId,
+        secretAccessKey: config.secretAccessKey
+      }
+    });
+
+    return r2Client;
+  } catch (error) {
+    const err = error as Error;
+    utils.print.debug(`R2 client initialization failed: ${err.message}`);
+    return null;
+  }
+}
+
+/**
+ * Check if R2 is configured
+ */
+export function isConfigured(): boolean {
+  return getR2Config() !== null;
+}
+
+/**
+ * Validate R2 credentials by testing connection
+ */
+export async function validateCredentials(): Promise<CredentialValidationResult> {
+  const client = getR2Client();
+  if (!client) {
+    return { valid: false, error: 'R2 credentials not configured' };
+  }
+
+  try {
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
+    const { HeadBucketCommand } = require('@aws-sdk/client-s3') as {
+      HeadBucketCommand: new (params: { Bucket: string }) => unknown;
+    };
+    const config = getR2Config();
+    if (!config) {
+      return { valid: false, error: 'R2 credentials not configured' };
+    }
+
+    await client.send(new HeadBucketCommand({ Bucket: config.bucketName }));
+    return { valid: true };
+  } catch (error) {
+    const err = error as Error & { name?: string };
+    if (err.name === 'NotFound') {
+      const config = getR2Config();
+      return { valid: false, error: `Bucket '${config?.bucketName || 'unknown'}' not found` };
+    }
+    return { valid: false, error: err.message };
+  }
+}
+
+// ============================================================================
+// Context Package Management
+// ============================================================================
+
+/**
+ * Check if a path should be excluded from sync
+ */
+function shouldExclude(relativePath: string): boolean {
+  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;
+}
+
+/**
+ * Recursively collect files from a directory
+ */
+function collectDirectoryFiles(
+  dirPath: string,
+  relativePath: string,
+  pkg: ContextPackage,
+  _projectRoot: string
+): void {
+  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 {
+          // Skip binary or unreadable files
+        }
+      }
+    }
+  } catch {
+    // Skip inaccessible directories
+  }
+}
+
+/**
+ * Generate a context package from project files
+ */
+export function generateContextPackage(projectRoot: string): ContextPackage {
+  const pkg: ContextPackage = {
+    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;
+}
+
+/**
+ * Compress context package
+ */
+export function compressPackage(pkg: ContextPackage): Buffer {
+  const json = JSON.stringify(pkg);
+  return zlib.gzipSync(json);
+}
+
+/**
+ * Decompress context package
+ */
+export function decompressPackage(data: Buffer): ContextPackage {
+  const json = zlib.gunzipSync(data).toString('utf-8');
+  return JSON.parse(json) as ContextPackage;
+}
+
+// ============================================================================
+// Sync Operations
+// ============================================================================
+
+/**
+ * Push context to R2
+ */
+export async function pushContext(
+  projectRoot: string,
+  projectId: string,
+  options: PushOptions = {}
+): Promise<PushResult> {
+  const client = getR2Client();
+  if (!client) {
+    return { success: false, error: 'R2 not configured' };
+  }
+
+  try {
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
+    const { PutObjectCommand } = require('@aws-sdk/client-s3') as {
+      PutObjectCommand: new (params: unknown) => unknown;
+    };
+    const config = getR2Config();
+    if (!config) {
+      return { success: false, error: 'R2 not configured' };
+    }
+
+    // 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: RemoteMetadata = {
+      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 || undefined
+    });
+
+    return {
+      success: true,
+      version,
+      fileCount: pkg.metadata.totalFiles,
+      totalSize: pkg.metadata.totalSize
+    };
+  } catch (error) {
+    const err = error as Error;
+    return { success: false, error: err.message };
+  }
+}
+
+/**
+ * Pull context from R2
+ */
+export async function pullContext(
+  projectRoot: string,
+  projectId: string,
+  options: PullOptions = {}
+): Promise<PullResult> {
+  const client = getR2Client();
+  if (!client) {
+    return { success: false, error: 'R2 not configured' };
+  }
+
+  try {
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
+    const { GetObjectCommand } = require('@aws-sdk/client-s3') as {
+      GetObjectCommand: new (params: unknown) => unknown;
+    };
+    const config = getR2Config();
+    if (!config) {
+      return { success: false, error: 'R2 not configured' };
+    }
+
+    // Determine which version to pull
+    const key = options.version
+      ? `${R2_PATHS.versions(projectId)}${options.version}/context.gz`
+      : `${R2_PATHS.latest(projectId)}context.gz`;
+
+    // Download
+    interface GetObjectResponse {
+      Body: AsyncIterable<Uint8Array>;
+      Metadata?: Record<string, string>;
+    }
+    const response = await client.send(new GetObjectCommand({
+      Bucket: config.bucketName,
+      Key: key
+    })) as GetObjectResponse;
+
+    // Read stream to buffer
+    const chunks: Uint8Array[] = [];
+    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 || undefined
+    });
+
+    return {
+      success: true,
+      version: response.Metadata?.['version'],
+      restoredCount,
+      totalSize: pkg.metadata.totalSize
+    };
+  } catch (error) {
+    const err = error as Error & { name?: string };
+    if (err.name === 'NoSuchKey') {
+      return { success: false, error: 'No remote context found' };
+    }
+    return { success: false, error: err.message };
+  }
+}
+
+/**
+ * Get sync status
+ */
+export async function getStatus(projectRoot: string, projectId: string): Promise<SyncStatus> {
+  const localState = getLocalSyncState(projectRoot);
+  const status: SyncStatus = {
+    configured: isConfigured(),
+    local: localState,
+    remote: null,
+    needsSync: false
+  };
+
+  if (!status.configured) {
+    return status;
+  }
+
+  try {
+    const client = getR2Client();
+    if (!client) {
+      return status;
+    }
+
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
+    const { GetObjectCommand } = require('@aws-sdk/client-s3') as {
+      GetObjectCommand: new (params: unknown) => unknown;
+    };
+    const config = getR2Config();
+    if (!config) {
+      return status;
+    }
+
+    interface GetObjectResponse {
+      Body: AsyncIterable<Uint8Array>;
+    }
+    const response = await client.send(new GetObjectCommand({
+      Bucket: config.bucketName,
+      Key: R2_PATHS.metadata(projectId)
+    })) as GetObjectResponse;
+
+    const chunks: Uint8Array[] = [];
+    for await (const chunk of response.Body) {
+      chunks.push(chunk);
+    }
+    status.remote = JSON.parse(Buffer.concat(chunks).toString('utf-8')) as RemoteMetadata;
+
+    // Check if sync needed
+    const localPkg = generateContextPackage(projectRoot);
+    status.local.currentChecksum = localPkg.metadata.checksum || undefined;
+    status.needsSync = localPkg.metadata.checksum !== status.remote?.checksum;
+  } catch (error) {
+    const err = error as Error & { name?: string };
+    if (err.name !== 'NoSuchKey') {
+      status.error = err.message;
+    }
+  }
+
+  return status;
+}
+
+/**
+ * List available versions
+ */
+export async function listVersions(projectId: string): Promise<string[]> {
+  const client = getR2Client();
+  if (!client) return [];
+
+  try {
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
+    const { ListObjectsV2Command } = require('@aws-sdk/client-s3') as {
+      ListObjectsV2Command: new (params: unknown) => unknown;
+    };
+    const config = getR2Config();
+    if (!config) return [];
+
+    interface ListResponse {
+      CommonPrefixes?: Array<{ Prefix?: string }>;
+    }
+    const response = await client.send(new ListObjectsV2Command({
+      Bucket: config.bucketName,
+      Prefix: R2_PATHS.versions(projectId),
+      Delimiter: '/'
+    })) as ListResponse;
+
+    return (response.CommonPrefixes || [])
+      .map(p => p.Prefix?.split('/').filter(Boolean).pop())
+      .filter((v): v is string => v !== undefined)
+      .sort()
+      .reverse();
+  } catch {
+    return [];
+  }
+}
+
+// ============================================================================
+// Local State Management
+// ============================================================================
+
+/**
+ * Get local sync state
+ */
+export function getLocalSyncState(projectRoot: string): LocalSyncState {
+  const statePath = path.join(projectRoot, SYNC_STATE_FILE);
+  if (fs.existsSync(statePath)) {
+    try {
+      return JSON.parse(fs.readFileSync(statePath, 'utf-8')) as LocalSyncState;
+    } catch {
+      return {};
+    }
+  }
+  return {};
+}
+
+/**
+ * Update local sync state
+ */
+export function updateLocalSyncState(projectRoot: string, updates: Partial<LocalSyncState>): void {
+  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: LocalSyncState = { ...current, ...updates, updatedAt: new Date().toISOString() };
+
+  fs.writeFileSync(statePath, JSON.stringify(updated, null, 2));
+}