@vibesdotdev/storage 0.0.1

package/src/docs/sync.docs.descriptor.ts

@@ -0,0 +1,281 @@
+import type { DocsTopicDescriptor } from '@vibesdotdev/docs';
+
+const descriptor: DocsTopicDescriptor = {
+	kind: 'docs/topic',
+	id: 'storage.sync',
+	title: 'Storage Sync',
+	summary: 'Cross-app synchronization, cloud-api adapter, and ownerApp pattern',
+	body: {
+		type: 'markdown',
+		sourceType: 'raw',
+		source: `---
+title: Storage Sync
+summary: Cross-app synchronization, cloud-api adapter, and ownerApp pattern
+tags: [storage, sync, cloud-api, ownerApp, synchronization]
+parent: storage
+order: 3
+surfaces: [cli, web, in-app]
+hardware: [consumer, cloud]
+---
+
+# Storage Sync
+
+Storage sync enables bidirectional synchronization of data between local storage and remote cloud storage. The \`storage/sync-bridge\` runtime kind declares which manifests should sync and how conflicts are resolved.
+
+## Sync Architecture
+
+\`\`\`
+┌─────────────────┐         ┌──────────────────┐
+│  Local Storage  │◄───────►│  Cloud Storage   │
+│  (libsql/D1)    │  sync   │  (cloud-api)     │
+└─────────────────┘         └──────────────────┘
+       │                           │
+       │                           │
+┌─────────────────┐         ┌──────────────────┐
+│  App A          │         │  App B           │
+│  (consumer)     │         │  (cloud)         │
+└─────────────────┘         └──────────────────┘
+\`\`\`
+
+## Sync Bridge Declaration
+
+Declare which manifests should sync:
+
+\`\`\`ts
+import type { SyncBridgeDescriptor } from '@vibesdotdev/storage';
+
+const syncBridge: SyncBridgeDescriptor = {
+  kind: 'storage/sync-bridge',
+  id: 'app.settings.sync',
+  title: 'App Settings Sync',
+  manifests: [
+    'app/settings',
+    'app/preferences',
+    'app/theme'
+  ],
+  ownerApp: 'settings-web',
+  conflictResolution: 'local-wins',
+  schedule: {
+    type: 'interval',
+    intervalMs: 300_000  // 5 minutes
+  }
+};
+\`\`\`
+
+## Sync State
+
+Sync state tracks the synchronization status:
+
+\`\`\`ts
+interface SyncState {
+  manifests: {
+    [manifestId: string]: {
+      localHash: string | null;
+      remoteHash: string | null;
+      lastSyncedAt: string;
+      syncStatus: 'in-sync' | 'local-ahead' | 'remote-ahead' | 'conflict' | 'error';
+      errorMessage?: string;
+    };
+  };
+  lastSyncAt: string;
+  syncStatus: 'idle' | 'syncing' | 'error';
+}
+\`\`\`
+
+## Manual Sync Operations
+
+### Pull from Cloud
+
+\`\`\`bash
+vibes storage sync pull --manifest app/settings
+\`\`\`
+
+**Behavior:**
+- Fetches remote data
+- Validates against local schema
+- Overwrites local data if remote is newer
+- Handles conflicts based on resolution strategy
+
+### Push to Cloud
+
+\`\`\`bash
+vibes storage sync push --manifest app/settings
+\`\`\`
+
+**Behavior:**
+- Serializes local data
+- Uploads to cloud-api endpoint
+- Updates sync state with remote hash
+- Handles upload errors gracefully
+
+### Check Sync Status
+
+\`\`\`bash
+vibes storage sync status
+\`\`\`
+
+**Output:**
+\`\`\`
+Manifest          Status        Last Synced
+─────────────────────────────────────────────
+app/settings      in-sync       2 minutes ago
+app/preferences   local-ahead   1 hour ago
+app/theme         conflict      3 hours ago
+\`\`\`
+
+### Resolve Conflicts
+
+\`\`\`bash
+vibes storage sync resolve --manifest app/theme --strategy local-wins
+\`\`\`
+
+**Conflict strategies:**
+- \`local-wins\` — Keep local data, overwrite remote
+- \`remote-wins\` — Keep remote data, overwrite local
+- \`merge\` — Attempt automatic merge (if possible)
+- \`manual\` — Mark for manual resolution
+
+## Cloud-API Adapter
+
+The cloud-api adapter enables remote storage access:
+
+\`\`\`ts
+import { storageAdapterCloudApiPlugin } from '@vibesdotdev/storage-adapter-cloud-api';
+
+await runtime.registerPlugin(storageAdapterCloudApiPlugin({
+  baseUrl: 'https://storage.vibes.dev',
+  authToken: process.env.CLOUD_AUTH_TOKEN,
+  endpoints: {
+    'app/settings': 'https://storage.vibes.dev/app/settings',
+    'app/preferences': 'https://storage.vibes.dev/app/preferences'
+  }
+}));
+\`\`\`
+
+### Endpoint Registration
+
+Manifests can declare their own cloud endpoints:
+
+\`\`\`ts
+const settingsManifest: StorageManifestDescriptor = {
+  kind: 'storage/manifest',
+  id: 'app/settings',
+  namespace: 'app',
+  adapterConfig: {
+    'storage.cloud-api': {
+      endpoint: 'https://storage.vibes.dev/app/settings'
+    }
+  }
+};
+\`\`\`
+
+## OwnerApp Pattern
+
+The \`ownerApp\` field declares which app owns the canonical data:
+
+\`\`\`ts
+{
+  ownerApp: 'settings-web'  // This app's data is canonical
+}
+\`\`\`
+
+**Implications:**
+- Owner app's data is the source of truth
+- Conflicts default to owner's version
+- Other apps sync from owner
+- Owner app handles conflict resolution
+
+## Sync Scheduling
+
+### Interval-Based Sync
+
+\`\`\`ts
+{
+  schedule: {
+    type: 'interval',
+    intervalMs: 300_000  // 5 minutes
+  }
+}
+\`\`\`
+
+### Event-Triggered Sync
+
+\`\`\`ts
+{
+  schedule: {
+    type: 'on-change',
+    debounceMs: 5000  // wait 5s after last change
+  }
+}
+\`\`\`
+
+### Manual Sync Only
+
+\`\`\`ts
+{
+  schedule: {
+    type: 'manual'  // only sync when explicitly triggered
+  }
+}
+\`\`\`
+
+## Dry-Run Mode
+
+Test sync behavior without making changes:
+
+\`\`\`bash
+vibes storage sync pull --manifest app/settings --dry-run
+\`\`\`
+
+**Output:**
+\`\`\`
+[dry-run] Would pull 3 manifests from cloud
+- app/settings: 1.2 KB (remote newer)
+- app/preferences: 0.8 KB (already in sync)
+- app/theme: 0.5 KB (conflict detected)
+\`\`\`
+
+## Error Handling
+
+Sync errors are tracked in sync state:
+
+\`\`\`ts
+interface SyncError {
+  manifestId: string;
+  error: 'network' | 'schema' | 'conflict' | 'auth';
+  message: string;
+  retryable: boolean;
+  retryAfter?: number;  // milliseconds
+}
+\`\`\`
+
+**Common errors:**
+- \`network\` — Cloud API unreachable (retryable)
+- \`schema\` — Remote data fails validation (not retryable)
+- \`conflict\` — Both local and remote changed (requires resolution)
+- \`auth\` — Authentication failed (refresh token)
+
+## Best Practices
+
+1. **Sync small, focused manifests** — Don't sync entire databases
+2. **Use appropriate conflict resolution** — Match strategy to data semantics
+3. **Monitor sync state** — Check \`vibes storage sync status\` regularly
+4. **Handle schema migrations** — Version your schemas for backward compatibility
+5. **Test with dry-run** — Always dry-run before production sync
+
+:::card{title="See also"}
+- [\`storage.adapters\`](storage.adapters) — Adapter implementations
+- [\`storage.manifests\`](storage.manifests) — Manifest declarations
+- [\`config.environment\`](config.environment) — Environment configuration
+:::
+`
+	},
+	parent: 'storage',
+	order: 3,
+	tags: ['storage', 'sync', 'cloud-api', 'ownerApp', 'synchronization'],
+	surfaces: ['cli', 'web', 'in-app'],
+	hardware: ['consumer', 'cloud'],
+	enabled: true
+};
+
+export default descriptor;

package/src/index.ts

@@ -0,0 +1,109 @@
+/**
+ * Storage Module
+ *
+ * Interface-driven storage providers for document and repository-style storage.
+ *
+ * @example
+ * ```typescript
+ * import { getVibesRuntime } from '@vibesdotdev/runtime';
+ * import storagePlugin, { StorageManifest } from '@vibesdotdev/storage';
+ *
+ * // Register the storage plugin
+ * await getVibesRuntime().registerPlugin(storagePlugin);
+ *
+ * // Use storage manifest
+ * const storage = new StorageManifest<MyData>('my.data');
+ * const data = await storage.load();
+ * ```
+ */
+
+// Plugin
+
+export { default as storagePlugin } from './storage.plugin';
+
+// Schemas
+
+export {
+	StorageProtocolSchema,
+	StorageCapabilitySchema,
+	StorageAdapterDescriptorSchema,
+	StorageDriveSchema,
+	StorageEntrySchema,
+	StorageScopeSchema,
+	StorageDataTypeSchema,
+	StorageCloudApiAdapterConfigSchema,
+	StorageManifestDescriptorSchema,
+	StorageRecordDescriptorSchema,
+	StorageSyncConfigSchema,
+	StorageRemoteCrudSchema,
+	StorageRemoteConfigSchema,
+	StoragePersistenceModeSchema,
+	StoragePersistencePolicySchema,
+	StorageOwnershipFilterSchema
+} from './schemas';
+
+export type {
+	StorageProtocol,
+	StorageCapability,
+	StorageAdapterDescriptor,
+	StorageDrive,
+	StorageEntry,
+	StorageScope,
+	StorageDataType,
+	StorageCloudApiAdapterConfig,
+	StorageManifestDescriptor,
+	StorageRecordDescriptor,
+	StorageRecordDescriptorInput,
+	StorageSyncConfig,
+	StorageRemoteCrud,
+	StorageRemoteConfig,
+	StoragePersistenceMode,
+	StoragePersistencePolicy,
+	StorageOwnershipFilter,
+	StorageSyncContext,
+	StorageRecordLocalSyncContext,
+	StorageRecordRemoteSyncContext,
+	StorageRecordSyncHooks
+} from './schemas';
+
+// Base Classes
+
+export { StorageManifest } from './manifest/base';
+
+// Interfaces
+
+export type {
+	StorageAdapterInterface,
+	StorageAdapterCapabilities,
+	StorageHealthStatus,
+	StorageDocumentStoreInterface,
+	KeyValueSetOptions,
+	StorageRepositoryInterface,
+	RepositoryOptions,
+	RepositoryCreateInput,
+	RepositoryUpdateInput,
+	RepositoryQuery,
+	RepositoryListOptions,
+	RepositoryFindOptions,
+	RepositoryOrderBy,
+	RepositoryPage,
+	RepositoryMeta,
+	StorageRecordInterface,
+	// Config types
+	FileBasedAdapterConfig,
+	LocalDBAdapterConfig,
+	JSONAdapterConfig,
+	MemoryAdapterConfig,
+	CloudAPIAdapterConfig,
+	// Query-builder database interface
+	QueryBuilderDatabase
+} from './interfaces';
+
+// Bridge (storage → runtime kind hydration)
+
+export { bridgeStorageKinds } from './bridge';
+export type { StorageKindBridgeConfig } from './bridge';
+
+// Client surface (consumer-facing query helpers)
+
+export { listBrowsableStorageAdapters } from './client';