@vibesdotdev/storage 0.0.1

package/dist/docs/sync.docs.descriptor.js

@@ -0,0 +1,279 @@
+const descriptor = {
+    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;
+//# sourceMappingURL=sync.docs.descriptor.js.map

package/dist/docs/sync.docs.descriptor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sync.docs.descriptor.js","sourceRoot":"","sources":["../../src/docs/sync.docs.descriptor.ts"],"names":[],"mappings":"AAEA,MAAM,UAAU,GAAwB;IACvC,IAAI,EAAE,YAAY;IAClB,EAAE,EAAE,cAAc;IAClB,KAAK,EAAE,cAAc;IACrB,OAAO,EAAE,oEAAoE;IAC7E,IAAI,EAAE;QACL,IAAI,EAAE,UAAU;QAChB,UAAU,EAAE,KAAK;QACjB,MAAM,EAAE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAoQT;KACC;IACD,MAAM,EAAE,SAAS;IACjB,KAAK,EAAE,CAAC;IACR,IAAI,EAAE,CAAC,SAAS,EAAE,MAAM,EAAE,WAAW,EAAE,UAAU,EAAE,iBAAiB,CAAC;IACrE,QAAQ,EAAE,CAAC,KAAK,EAAE,KAAK,EAAE,QAAQ,CAAC;IAClC,QAAQ,EAAE,CAAC,UAAU,EAAE,OAAO,CAAC;IAC/B,OAAO,EAAE,IAAI;CACb,CAAC;AAEF,eAAe,UAAU,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,27 @@
+/**
+ * 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();
+ * ```
+ */
+export { default as storagePlugin } from './storage.plugin';
+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';
+export { StorageManifest } from './manifest/base';
+export type { StorageAdapterInterface, StorageAdapterCapabilities, StorageHealthStatus, StorageDocumentStoreInterface, KeyValueSetOptions, StorageRepositoryInterface, RepositoryOptions, RepositoryCreateInput, RepositoryUpdateInput, RepositoryQuery, RepositoryListOptions, RepositoryFindOptions, RepositoryOrderBy, RepositoryPage, RepositoryMeta, StorageRecordInterface, FileBasedAdapterConfig, LocalDBAdapterConfig, JSONAdapterConfig, MemoryAdapterConfig, CloudAPIAdapterConfig, QueryBuilderDatabase } from './interfaces';
+export { bridgeStorageKinds } from './bridge';
+export type { StorageKindBridgeConfig } from './bridge';
+export { listBrowsableStorageAdapters } from './client';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAIH,OAAO,EAAE,OAAO,IAAI,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAI5D,OAAO,EACN,qBAAqB,EACrB,uBAAuB,EACvB,8BAA8B,EAC9B,kBAAkB,EAClB,kBAAkB,EAClB,kBAAkB,EAClB,qBAAqB,EACrB,kCAAkC,EAClC,+BAA+B,EAC/B,6BAA6B,EAC7B,uBAAuB,EACvB,uBAAuB,EACvB,yBAAyB,EACzB,4BAA4B,EAC5B,8BAA8B,EAC9B,4BAA4B,EAC5B,MAAM,WAAW,CAAC;AAEnB,YAAY,EACX,eAAe,EACf,iBAAiB,EACjB,wBAAwB,EACxB,YAAY,EACZ,YAAY,EACZ,YAAY,EACZ,eAAe,EACf,4BAA4B,EAC5B,yBAAyB,EACzB,uBAAuB,EACvB,4BAA4B,EAC5B,iBAAiB,EACjB,iBAAiB,EACjB,mBAAmB,EACnB,sBAAsB,EACtB,wBAAwB,EACxB,sBAAsB,EACtB,kBAAkB,EAClB,6BAA6B,EAC7B,8BAA8B,EAC9B,sBAAsB,EACtB,MAAM,WAAW,CAAC;AAInB,OAAO,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAIlD,YAAY,EACX,uBAAuB,EACvB,0BAA0B,EAC1B,mBAAmB,EACnB,6BAA6B,EAC7B,kBAAkB,EAClB,0BAA0B,EAC1B,iBAAiB,EACjB,qBAAqB,EACrB,qBAAqB,EACrB,eAAe,EACf,qBAAqB,EACrB,qBAAqB,EACrB,iBAAiB,EACjB,cAAc,EACd,cAAc,EACd,sBAAsB,EAEtB,sBAAsB,EACtB,oBAAoB,EACpB,iBAAiB,EACjB,mBAAmB,EACnB,qBAAqB,EAErB,oBAAoB,EACpB,MAAM,cAAc,CAAC;AAItB,OAAO,EAAE,kBAAkB,EAAE,MAAM,UAAU,CAAC;AAC9C,YAAY,EAAE,uBAAuB,EAAE,MAAM,UAAU,CAAC;AAIxD,OAAO,EAAE,4BAA4B,EAAE,MAAM,UAAU,CAAC"}

package/dist/index.js

@@ -0,0 +1,29 @@
+/**
+ * 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.js';
+// Schemas
+export { StorageProtocolSchema, StorageCapabilitySchema, StorageAdapterDescriptorSchema, StorageDriveSchema, StorageEntrySchema, StorageScopeSchema, StorageDataTypeSchema, StorageCloudApiAdapterConfigSchema, StorageManifestDescriptorSchema, StorageRecordDescriptorSchema, StorageSyncConfigSchema, StorageRemoteCrudSchema, StorageRemoteConfigSchema, StoragePersistenceModeSchema, StoragePersistencePolicySchema, StorageOwnershipFilterSchema } from './schemas';
+// Base Classes
+export { StorageManifest } from './manifest/base.js';
+// Bridge (storage → runtime kind hydration)
+export { bridgeStorageKinds } from './bridge';
+// Client surface (consumer-facing query helpers)
+export { listBrowsableStorageAdapters } from './client';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,SAAS;AAET,OAAO,EAAE,OAAO,IAAI,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAE5D,UAAU;AAEV,OAAO,EACN,qBAAqB,EACrB,uBAAuB,EACvB,8BAA8B,EAC9B,kBAAkB,EAClB,kBAAkB,EAClB,kBAAkB,EAClB,qBAAqB,EACrB,kCAAkC,EAClC,+BAA+B,EAC/B,6BAA6B,EAC7B,uBAAuB,EACvB,uBAAuB,EACvB,yBAAyB,EACzB,4BAA4B,EAC5B,8BAA8B,EAC9B,4BAA4B,EAC5B,MAAM,WAAW,CAAC;AA0BnB,eAAe;AAEf,OAAO,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AA+BlD,4CAA4C;AAE5C,OAAO,EAAE,kBAAkB,EAAE,MAAM,UAAU,CAAC;AAG9C,iDAAiD;AAEjD,OAAO,EAAE,4BAA4B,EAAE,MAAM,UAAU,CAAC"}