@vibesdotdev/storage 0.0.1

package/src/daemon/commands/sync.ts

@@ -0,0 +1,225 @@
+/**
+ * Sync Command Handlers
+ *
+ * RPC commands for storage sync operations:
+ * - sync.status  -> Returns sync state for all manifests
+ * - sync.trigger -> Enqueues an immediate sync job
+ * - sync.resolve -> Resolves a conflict (keep-local or keep-remote)
+ */
+
+import type {
+	RuntimeCommandDeps,
+	RuntimeCommandPayload,
+	RuntimeCommandResult
+} from '@vibesdotdev/runtime-plugin-types';
+
+/**
+ * Handle `sync.status` — returns current sync state for all manifests.
+ */
+export async function handleSyncStatus(
+	_message: RuntimeCommandPayload,
+	deps: RuntimeCommandDeps
+): Promise<RuntimeCommandResult> {
+	const { loadSyncState } = await import('../../sync/sync-state.consumer');
+	const state = await loadSyncState();
+
+	// Also check if sync is enabled
+	let syncEnabled = false;
+	try {
+		const manifest = await deps.runtime
+			.query('config/manifest')
+			.filter((d: { id: string }) => d.id === 'ai.core')
+			.resolve();
+
+		if (manifest) {
+			const config = manifest as { load(): Promise<Record<string, unknown> | null> };
+			const data = await config.load();
+			syncEnabled = data?.syncToCloud === true;
+		}
+	} catch {
+		// Config not available
+	}
+
+	return {
+		success: true,
+		syncEnabled,
+		updatedAt: state.updatedAt,
+		manifests: state.manifests,
+		summary: {
+			total: Object.keys(state.manifests).length,
+			inSync: Object.values(state.manifests).filter((m) => m.syncStatus === 'in-sync').length,
+			localAhead: Object.values(state.manifests).filter((m) => m.syncStatus === 'local-ahead')
+				.length,
+			remoteAhead: Object.values(state.manifests).filter((m) => m.syncStatus === 'remote-ahead')
+				.length,
+			conflicts: Object.values(state.manifests).filter((m) => m.syncStatus === 'conflict').length,
+			paused: Object.values(state.manifests).filter((m) => m.syncStatus === 'paused').length,
+			neverSynced: Object.values(state.manifests).filter((m) => m.syncStatus === 'never-synced')
+				.length
+		}
+	};
+}
+
+/**
+ * Handle `sync.trigger` — enqueues an immediate storage-sync job.
+ */
+export async function handleSyncTrigger(
+	message: RuntimeCommandPayload,
+	deps: RuntimeCommandDeps
+): Promise<RuntimeCommandResult> {
+	const manifestIds = (message.manifestIds as string[]) ?? [];
+	const force = (message.force as boolean) ?? true;
+
+	// Broadcast that sync was triggered
+	deps.subscriptionManager.broadcast?.('activity', {
+		type: 'sync-triggered',
+		manifestIds,
+		force,
+		timestamp: new Date().toISOString()
+	});
+
+	// Run pull + push inline (for RPC response)
+	const { pullFromCloud } = await import('../../sync/cloud-pull');
+	const pullResult = await pullFromCloud({ manifestIds, force });
+	const { SyncBridge } = await import('../../sync/sync-bridge');
+	const { resolveSyncTarget } = await import('../../sync/resolve-sync-target');
+
+	const bridgeDescriptors = deps.runtime
+		.query('storage/sync-bridge')
+		.enabled()
+		.descriptors() as Array<{ id: string }>;
+	const bridgeTargets =
+		manifestIds.length > 0
+			? bridgeDescriptors.filter((descriptor) => manifestIds.includes(descriptor.id))
+			: bridgeDescriptors;
+
+	const bridgeResults: Array<{
+		bridgeId: string;
+		pushed: number;
+		pulled: number;
+		skipped: number;
+		conflicts: number;
+		errors: number;
+	}> = [];
+
+	if (bridgeTargets.length > 0) {
+		const { syncTarget, apiToken } = await resolveSyncTarget();
+		if (syncTarget && syncTarget !== 'unknown') {
+			for (const descriptor of bridgeTargets) {
+				const bridge = new SyncBridge(descriptor as never);
+				const result = await bridge.execute(
+					syncTarget,
+					{ direction: 'both', dryRun: false, force },
+					apiToken
+				);
+				bridgeResults.push({
+					bridgeId: result.bridgeId,
+					pushed: result.pushed,
+					pulled: result.pulled,
+					skipped: result.skipped,
+					conflicts: result.conflicts,
+					errors: result.errors
+				});
+			}
+		}
+	}
+
+	return {
+		success: true,
+		triggered: true,
+		pullResult,
+		bridgeResults,
+		message: `Sync triggered. Pulled: ${pullResult.pulled}, Conflicts: ${pullResult.conflicts}, Bridges: ${bridgeResults.length}`
+	};
+}
+
+/**
+ * Handle `sync.resolve` — resolves a manifest conflict.
+ * Accepts { manifestId, resolution: 'keep-local' | 'keep-remote' }
+ */
+export async function handleSyncResolve(
+	message: RuntimeCommandPayload,
+	deps: RuntimeCommandDeps
+): Promise<RuntimeCommandResult> {
+	const manifestId = message.manifestId as string;
+	const resolution = message.resolution as 'keep-local' | 'keep-remote';
+
+	if (!manifestId || !resolution) {
+		return { success: false, error: 'Missing manifestId or resolution' };
+	}
+
+	const { loadSyncState, saveSyncState, getManifestSyncState, markSynced, computeHash } =
+		await import('../../sync/sync-state.consumer');
+
+	const syncState = await loadSyncState();
+	const manifestState = getManifestSyncState(syncState, manifestId);
+
+	if (manifestState.syncStatus !== 'conflict') {
+		return { success: false, error: `Manifest ${manifestId} is not in conflict state` };
+	}
+
+	if (resolution === 'keep-local') {
+		// Push local to cloud
+		const { StorageManifest } = await import('../../manifest/base');
+		const localManifest = new StorageManifest(manifestId);
+		const localData = await localManifest.load();
+
+		if (localData) {
+			try {
+				const cloudAdapter = await deps.runtime
+					.query('storage/adapter')
+					.filter((d: { id: string }) => d.id === 'storage.cloud-api')
+					.resolve();
+
+				if (cloudAdapter) {
+					const descriptor = deps.runtime
+						.query('storage/manifest')
+						.filter((d: { id: string }) => d.id === manifestId)
+						.firstDescriptor() as unknown as {
+						namespace: string;
+						schema: unknown;
+						config?: Record<string, Record<string, unknown>>;
+					};
+
+					const adapter = cloudAdapter as {
+						configure(config: Record<string, unknown>): void;
+						documentStore<T>(ns: string, schema: unknown): { save(data: T): Promise<void> };
+					};
+
+					const cloudConfig = descriptor?.config?.['storage.cloud-api'] ?? {};
+					adapter.configure(cloudConfig);
+					const store = adapter.documentStore<unknown>(descriptor.namespace, descriptor.schema);
+					await store.save(localData);
+				}
+			} catch {
+				return { success: false, error: 'Failed to push local data to cloud' };
+			}
+		}
+
+		const hash = localData ? computeHash(localData) : '';
+		markSynced(syncState, manifestId, hash, 'push');
+	} else {
+		// Pull remote to local
+		const { pullFromCloud } = await import('../../sync/cloud-pull');
+		await pullFromCloud({ manifestIds: [manifestId], force: true });
+		// pullFromCloud updates syncState internally, but we need fresh state
+		const freshState = await loadSyncState();
+		Object.assign(syncState, freshState);
+	}
+
+	await saveSyncState(syncState);
+
+	deps.subscriptionManager.broadcast?.('activity', {
+		type: 'sync-conflict-resolved',
+		manifestId,
+		resolution,
+		timestamp: new Date().toISOString()
+	});
+
+	return {
+		success: true,
+		manifestId,
+		resolution,
+		newStatus: getManifestSyncState(syncState, manifestId).syncStatus
+	};
+}

package/src/docs/adapters.docs.descriptor.ts

@@ -0,0 +1,225 @@
+import type { DocsTopicDescriptor } from '@vibesdotdev/docs';
+
+const descriptor: DocsTopicDescriptor = {
+	kind: 'docs/topic',
+	id: 'storage.adapters',
+	title: 'Storage Adapters',
+	summary: 'Storage adapter interface, adapter implementations (libsql/D1/memory), and registration',
+	body: {
+		type: 'markdown',
+		sourceType: 'raw',
+		source: `---
+title: Storage Adapters
+summary: Storage adapter interface, adapter implementations (libsql/D1/memory), and registration
+tags: [storage, adapters, interface, registration]
+parent: storage
+order: 1
+surfaces: [cli, web, in-app]
+hardware: [consumer, cloud]
+---
+
+# Storage Adapters
+
+Storage adapters provide the persistence layer for the vibes storage system. The \`storage/adapter\` runtime kind defines the interface that all adapters must implement.
+
+## Adapter Interface
+
+All adapters implement the \`StorageAdapterInterface\`:
+
+\`\`\`ts
+interface StorageAdapterInterface {
+  // Document operations
+  documentStore<T>(namespace: string, schema: ZodSchema<T>): {
+    load(): Promise<T | null>;
+    save(data: T): Promise<void>;
+    exists(): Promise<boolean>;
+    delete(): Promise<void>;
+  };
+
+  // Repository operations
+  repository<T>(namespace: string, schema: ZodSchema<T>): {
+    find(id: string): Promise<T | null>;
+    findAll(query?: Query): Promise<T[]>;
+    insert(data: T): Promise<T>;
+    update(id: string, data: Partial<T>): Promise<T>;
+    delete(id: string): Promise<void>;
+  };
+
+  // Lifecycle
+  ensureReady(): Promise<void>;
+  close(): Promise<void>;
+}
+\`\`\`
+
+## Available Adapters
+
+### Memory Adapter
+
+In-memory storage for testing and ephemeral use:
+
+\`\`\`ts
+import { storageAdapterMemoryPlugin } from '@vibesdotdev/storage-adapter-memory';
+await runtime.registerPlugin(storageAdapterMemoryPlugin);
+\`\`\`
+
+**Use cases:**
+- Unit and integration tests
+- Development prototyping
+- Caching layers
+
+**Limitations:**
+- Data lost on process restart
+- No concurrent access support
+
+### LibSQL Adapter
+
+Local SQLite storage using libsql:
+
+\`\`\`ts
+import { storageAdapterLibsqlPlugin } from '@vibesdotdev/storage-adapter-libsql';
+await runtime.registerPlugin(storageAdapterLibsqlPlugin({
+  dbUrl: 'file:local.db'
+}));
+\`\`\`
+
+**Use cases:**
+- Single-user desktop apps
+- Local-first applications
+- Edge computing scenarios
+
+### D1 Adapter
+
+Cloudflare D1 database adapter:
+
+\`\`\`ts
+import { storageAdapterD1Plugin } from '@vibesdotdev/storage-adapter-d1';
+await runtime.registerPlugin(storageAdapterD1Plugin({
+  binding: env.DB  // Cloudflare D1 binding
+}));
+\`\`\`
+
+**Use cases:**
+- Cloudflare Workers deployments
+- Serverless applications
+- Multi-tenant SaaS
+
+### Drizzle ORM Adapter
+
+Database-agnostic adapter via Drizzle ORM:
+
+\`\`\`ts
+import { storageAdapterDrizzlePlugin } from '@vibesdotdev/storage-adapter-drizzle';
+import { drizzle } from 'drizzle-orm/postgres-js';
+import postgres from 'postgres';
+
+const client = postgres(process.env.DATABASE_URL!);
+const db = drizzle(client);
+
+await runtime.registerPlugin(storageAdapterDrizzlePlugin({ db }));
+\`\`\`
+
+**Use cases:**
+- Production PostgreSQL deployments
+- Complex queries and relations
+- Migration management
+
+### Cloud-API Adapter
+
+Remote storage via HTTP API (used for sync):
+
+\`\`\`ts
+import { storageAdapterCloudApiPlugin } from '@vibesdotdev/storage-adapter-cloud-api';
+await runtime.registerPlugin(storageAdapterCloudApiPlugin({
+  baseUrl: 'https://storage.vibes.dev',
+  authToken: '...'
+}));
+\`\`\`
+
+**Use cases:**
+- Cross-app sync (see \`storage.sync\`)
+- Centralized backup
+- Multi-device synchronization
+
+## Adapter Registration
+
+Adapters register themselves via runtime plugins:
+
+\`\`\`ts
+import { getVibesRuntime } from '@vibesdotdev/runtime';
+import { storagePlugin } from '@vibesdotdev/storage';
+import { storageAdapterMemoryPlugin } from '@vibesdotdev/storage-adapter-memory';
+
+const runtime = getVibesRuntime();
+
+// Register core storage first
+await runtime.registerPlugin(storagePlugin);
+
+// Then register adapter
+await runtime.registerPlugin(storageAdapterMemoryPlugin);
+\`\`\`
+
+## Adapter Resolution
+
+The runtime resolves adapters based on hardware scope:
+
+\`\`\`ts
+// Runtime auto-selects based on scope
+const adapter = await runtime.query('storage/adapter')
+  .forHardware('consumer')
+  .resolve();
+
+// Or filter explicitly
+const adapter = await runtime.query('storage/adapter')
+  .filter(d => d.id === 'storage.adapter.libsql')
+  .resolve();
+\`\`\`
+
+**Resolution priority:**
+1. Explicit filter match
+2. Hardware compatibility
+3. Persistent over memory adapters
+4. First registered
+
+## Writing Custom Adapters
+
+Create a plugin that registers a \`storage/adapter\` descriptor:
+
+\`\`\`ts
+import { createRuntimePlugin } from '@vibesdotdev/runtime';
+import type { StorageAdapterDescriptor } from '@vibesdotdev/storage';
+
+const descriptor: StorageAdapterDescriptor = {
+  kind: 'storage/adapter',
+  id: 'storage.adapter.custom',
+  title: 'Custom Adapter',
+  persistent: true,
+  hardware: ['consumer', 'cloud']
+};
+
+export const customAdapterPlugin = createRuntimePlugin({
+  id: 'custom-adapter',
+  kinds: [{
+    id: 'storage/adapter',
+    descriptorSchema: StorageAdapterDescriptorSchema,
+    defaultImplementation: CustomAdapterImpl
+  }],
+  descriptors: [descriptor]
+});
+\`\`\`
+
+:::card{title="See also"}
+- [\`storage.manifests\`](storage.manifests) — Manifest declarations
+- [\`storage.records\`](storage.records) — Record CRUD operations
+- [\`storage.sync\`](storage.sync) — Cross-app synchronization
+:::
+`
+	},
+	parent: 'storage',
+	order: 1,
+	tags: ['storage', 'adapters', 'interface', 'registration'],
+	surfaces: ['cli', 'web', 'in-app'],
+	hardware: ['consumer', 'cloud'],
+	enabled: true
+};
+
+export default descriptor;