@vibesdotdev/storage 0.0.1

package/src/cli/commands/sync/status/storage.sync.status.cli-command.impl.ts

@@ -0,0 +1,192 @@
+/**
+ * vibes storage sync status
+ *
+ * Displays the sync state for all cloud-eligible storage manifests
+ * AND all registered sync-bridge descriptors.
+ * Shows the current environment's sync target URL, per-item sync status,
+ * last sync time, direction, and any errors.
+ */
+
+import { getVibesRuntime } from '@vibesdotdev/runtime';
+import type { StorageCliUIContext as UIContext } from '../../../types';
+import { loadSyncState, getManifestSyncState } from '../../../../sync/sync-state.consumer';
+import type { ManifestSyncState } from '../../../../sync/schemas/sync-state';
+import type { SyncBridgeDescriptor } from '../../../../schemas/sync-bridge-descriptor';
+import type { StorageRecordDescriptor } from '../../../../schemas/record';
+import { resolveSyncTarget } from '../../../../sync/resolve-sync-target';
+import {
+	createRecordSyncBridgeDescriptor,
+	isSyncableStorageRecord
+} from '../../../../sync/record-sync-bridge';
+
+interface ManifestDescriptor {
+	id: string;
+	namespace: string;
+	allowedAdapters?: string[];
+	enabled?: boolean;
+}
+
+function formatTimeAgo(isoString: string | null): string {
+	if (!isoString) return '—';
+	const diff = Date.now() - new Date(isoString).getTime();
+	const seconds = Math.floor(diff / 1000);
+	if (seconds < 60) return `${seconds}s ago`;
+	const minutes = Math.floor(seconds / 60);
+	if (minutes < 60) return `${minutes}m ago`;
+	const hours = Math.floor(minutes / 60);
+	if (hours < 24) return `${hours}h ago`;
+	const days = Math.floor(hours / 24);
+	return `${days}d ago`;
+}
+
+function statusIcon(status: ManifestSyncState['syncStatus']): string {
+	switch (status) {
+		case 'in-sync':
+			return 'in-sync';
+		case 'local-ahead':
+			return 'local-ahead';
+		case 'remote-ahead':
+			return 'remote-ahead';
+		case 'conflict':
+			return 'CONFLICT';
+		case 'paused':
+			return 'paused';
+		case 'never-synced':
+		default:
+			return 'never-synced';
+	}
+}
+
+export default {
+	async execute(_args: Record<string, unknown>, opts: Record<string, unknown>): Promise<void> {
+		const runtime = getVibesRuntime();
+		const ui = (await runtime.context('cli/ui')) as UIContext;
+
+		try {
+			// Resolve current environment for sync target display
+			const { syncTarget, envName } = await resolveSyncTarget();
+
+			// Load sync state
+			const syncState = await loadSyncState();
+
+			// ── Storage Manifests ──
+			const descriptors = runtime
+				.query('storage/manifest')
+				.descriptors() as unknown as ManifestDescriptor[];
+
+			const eligible = descriptors.filter(
+				(d) => d.enabled !== false && d.allowedAdapters?.includes('storage.cloud-api')
+			);
+
+			// ── Sync Bridges / Records ──
+			const bridges = runtime.query('storage/sync-bridge').descriptors() as SyncBridgeDescriptor[];
+			const records = (runtime.query('storage/record').descriptors() as StorageRecordDescriptor[])
+				.filter(isSyncableStorageRecord)
+				.map(createRecordSyncBridgeDescriptor);
+			const syncTargets = [...records, ...bridges];
+
+			if (opts.json) {
+				const manifestData = eligible.map((d) => {
+					const state = getManifestSyncState(syncState, d.id);
+					return {
+						type: 'manifest',
+						namespace: d.namespace,
+						...state,
+						syncTarget
+					};
+				});
+				const bridgeData = syncTargets.map((b) => {
+					// Bridges use composite keys: bridgeId:entityId
+					// For status overview, show the bridge-level summary
+					const stateKeys = Object.keys(syncState.manifests).filter((k) =>
+						k.startsWith(`${b.id}:`)
+					);
+					const entityCount = stateKeys.length;
+					const synced = stateKeys.filter(
+						(k) => syncState.manifests[k]?.syncStatus === 'in-sync'
+					).length;
+					return {
+						type: 'bridge',
+						bridgeId: b.id,
+						sourceKind: b.source.runtimeKind,
+						apiPath: b.target.apiPath,
+						direction: b.sync.direction,
+						entities: entityCount,
+						synced,
+						syncTarget
+					};
+				});
+				ui.render(
+					{ syncTarget, envName, manifests: manifestData, bridges: bridgeData },
+					{ format: 'json' }
+				);
+				return;
+			}
+
+			ui.info(`Sync Target: ${syncTarget} (${envName})`);
+			ui.log('');
+
+			// Show storage manifests
+			if (eligible.length > 0) {
+				ui.info('Storage Manifests:');
+				ui.table(
+					eligible.map((d) => {
+						const state = getManifestSyncState(syncState, d.id);
+						return {
+							Manifest: d.id,
+							Status: statusIcon(state.syncStatus),
+							'Last Sync': formatTimeAgo(state.lastSyncAt),
+							Dir: state.lastSyncDirection ?? '—',
+							Error: state.errorMessage ? state.errorMessage.slice(0, 40) : '—'
+						};
+					}),
+					{ columns: ['Manifest', 'Status', 'Last Sync', 'Dir', 'Error'] }
+				);
+			} else {
+				ui.info('No storage manifests have cloud sync enabled.');
+			}
+
+			// Show sync bridges
+			if (syncTargets.length > 0) {
+				ui.log('');
+				ui.info('Record / Bridge Sync Targets:');
+				ui.table(
+					syncTargets.map((b) => {
+						const stateKeys = Object.keys(syncState.manifests).filter((k) =>
+							k.startsWith(`${b.id}:`)
+						);
+						const entityCount = stateKeys.length;
+						const synced = stateKeys.filter(
+							(k) => syncState.manifests[k]?.syncStatus === 'in-sync'
+						).length;
+						const errors = stateKeys.filter((k) => syncState.manifests[k]?.errorMessage).length;
+						const lastSync =
+							stateKeys
+								.map((k) => syncState.manifests[k]?.lastSyncAt)
+								.filter(Boolean)
+								.sort()
+								.pop() ?? null;
+
+						return {
+							Target: b.id,
+							Source: b.source.runtimeKind,
+							API: b.target.apiPath,
+							Dir: b.sync.direction.replace('bidirectional', 'both'),
+							Synced: entityCount > 0 ? `${synced}/${entityCount}` : 'never',
+							'Last Sync': formatTimeAgo(lastSync),
+							Errors: errors > 0 ? String(errors) : '—'
+						};
+					}),
+					{ columns: ['Target', 'Source', 'API', 'Dir', 'Synced', 'Last Sync', 'Errors'] }
+				);
+			}
+
+			if (eligible.length === 0 && syncTargets.length === 0) {
+				ui.warn('No syncable targets found.');
+			}
+		} catch (e) {
+			ui.error(`Failed to get sync status: ${e}`);
+			process.exit(1);
+		}
+	}
+};

package/src/cli/context.consumer.ts

@@ -0,0 +1,195 @@
+/**
+ * Storage Context Consumer
+ *
+ * Provides storage context for consumer hardware scope.
+ * Uses runtime-injected fs/crypto/path abstraction to avoid
+ * universal core importing Node.js built-ins directly.
+ */
+
+import { getConsumerFs, type ConsumerFileSystem } from '../interfaces/storage-consumer-fs';
+import { resolveWorkspacePath } from '../paths';
+
+const STORAGE_ROOT = '.vibes/storage';
+const PROJECT_JSON_PREFIX = 'project/json/';
+
+function sanitizeNamespace(namespace: string): string {
+	return namespace.replace(/[^a-zA-Z0-9._-]/g, '-');
+}
+
+async function getProjectJsonDir(fs: ConsumerFileSystem): Promise<string> {
+	return fs.join(await resolveWorkspaceRoot(fs), STORAGE_ROOT, 'project', 'json');
+}
+
+async function getProjectJsonFile(fs: ConsumerFileSystem, namespace: string): Promise<string> {
+	return fs.join(await getProjectJsonDir(fs), `${sanitizeNamespace(namespace)}.json`);
+}
+
+async function resolveWorkspaceRoot(fs: ConsumerFileSystem): Promise<string> {
+	const fromContextPath = await findWorkspaceRoot(fs, resolveWorkspacePath());
+	if (fromContextPath) {
+		return fromContextPath;
+	}
+
+	const fromCwd = await findWorkspaceRoot(fs, fs.resolve('.'));
+	if (fromCwd) {
+		return fromCwd;
+	}
+
+	const fromModulePath = await findWorkspaceRoot(fs, fs.resolve(import.meta.dir, '../../../../../'));
+	if (fromModulePath) {
+		return fromModulePath;
+	}
+
+	return resolveWorkspacePath();
+}
+
+async function findWorkspaceRoot(fs: ConsumerFileSystem, startPath: string): Promise<string | null> {
+	let current = fs.resolve(startPath);
+	let previous = '';
+
+	while (current !== previous) {
+		const hasPackage = fs.existsSync(fs.join(current, 'package.json'));
+		const hasVibesBin = fs.existsSync(fs.join(current, 'src', 'bin', 'vibes.ts'));
+		if (hasPackage && hasVibesBin) {
+			return current;
+		}
+		previous = current;
+		current = fs.dirname(current);
+	}
+
+	return null;
+}
+
+async function readJson<T>(fs: ConsumerFileSystem, filePath: string): Promise<T | null> {
+	try {
+		const raw = await fs.readFile(filePath, 'utf8');
+		if (!raw.trim()) {
+			return null;
+		}
+		return JSON.parse(raw) as T;
+	} catch (error) {
+		if (error instanceof Error && 'code' in error && error.code === 'ENOENT') {
+			return null;
+		}
+		throw error;
+	}
+}
+
+async function writeJson<T>(fs: ConsumerFileSystem, filePath: string, value: T): Promise<void> {
+	const dir = fs.dirname(filePath);
+	fs.mkdirSync(dir, { recursive: true });
+
+	const payload = `${JSON.stringify(value, null, 2)}\n`;
+	const tmpFile = `${filePath}.tmp.${process.pid}.${Date.now()}.${fs.randomUUID()}`;
+	await fs.writeFile(tmpFile, payload, 'utf8');
+	try {
+		await fs.rename(tmpFile, filePath);
+	} catch (error) {
+		if (error instanceof Error && 'code' in error && error.code === 'ENOENT') {
+			fs.mkdirSync(dir, { recursive: true });
+			await fs.writeFile(filePath, payload, 'utf8');
+			return;
+		}
+		throw error;
+	}
+}
+
+export async function getStorageContext(): Promise<{
+	project: {
+		json: <T>(namespace: string) => {
+			read: () => Promise<T | null>;
+			write: (value: T) => Promise<void>;
+		};
+	};
+}> {
+	const fs = await getConsumerFs();
+	const dir = await getProjectJsonDir(fs);
+	fs.mkdirSync(dir, { recursive: true });
+
+	return {
+		project: {
+			json: <T>(namespace: string) => {
+				const filePathPromise = getProjectJsonFile(fs, namespace);
+				return {
+					read: async () => {
+						const filePath = await filePathPromise;
+						return readJson<T>(fs, filePath);
+					},
+					write: async (value: T) => {
+						const filePath = await filePathPromise;
+						return writeJson(fs, filePath, value);
+					}
+				};
+			}
+		}
+	};
+}
+
+export async function subscribeStorage<T>(
+	resource: string,
+	handler: (event: { value: T | null }) => void,
+	options?: { delivery?: { type: 'debounce'; ms: number } }
+): Promise<{ unsubscribe: () => void }> {
+	if (!resource.startsWith(PROJECT_JSON_PREFIX)) {
+		return { unsubscribe: () => undefined };
+	}
+
+	const fs = await getConsumerFs();
+	const namespace = resource.slice(PROJECT_JSON_PREFIX.length);
+	const filePath = await getProjectJsonFile(fs, namespace);
+	const dir = fs.dirname(filePath);
+	const targetFile = fs.basename(filePath);
+	const debounceMs = options?.delivery?.type === 'debounce' ? options.delivery.ms : 0;
+
+	fs.mkdirSync(dir, { recursive: true });
+
+	let timer: NodeJS.Timeout | null = null;
+	let watcher: { close(): void } | null = null;
+
+	const emitChange = async () => {
+		try {
+			const value = await readJson<T>(fs, filePath);
+			handler({ value });
+		} catch {
+			// ignore read errors
+		}
+	};
+
+	const scheduleEmit = () => {
+		if (debounceMs <= 0) {
+			void emitChange();
+			return;
+		}
+		if (timer) {
+			clearTimeout(timer);
+		}
+		timer = setTimeout(() => {
+			timer = null;
+			void emitChange();
+		}, debounceMs);
+	};
+
+	try {
+		watcher = fs.watch(dir, (eventType, filename) => {
+			const name = filename?.toString ? filename.toString() : filename;
+			if (!name || name !== targetFile) {
+				return;
+			}
+			if (eventType === 'change' || eventType === 'rename') {
+				scheduleEmit();
+			}
+		});
+	} catch {
+		watcher = null;
+	}
+
+	return {
+		unsubscribe: () => {
+			if (timer) {
+				clearTimeout(timer);
+				timer = null;
+			}
+			watcher?.close();
+		}
+	};
+}

package/src/cli/storage.cli-group.descriptor.ts

@@ -0,0 +1,13 @@
+import type { CLIGroupAssetDescriptor } from '@vibesdotdev/runtime/schemas/asset';
+
+const descriptor: CLIGroupAssetDescriptor = {
+	kind: 'cli/group',
+	id: 'storage',
+	name: 'storage',
+	description: 'Storage and sync management',
+	surfaces: ['cli'],
+	hardware: ['consumer'],
+	enabled: true
+};
+
+export default descriptor;

package/src/cli/storage.sync.cli-group.descriptor.ts

@@ -0,0 +1,14 @@
+import type { CLIGroupAssetDescriptor } from '@vibesdotdev/runtime/schemas/asset';
+
+const descriptor: CLIGroupAssetDescriptor = {
+	kind: 'cli/group',
+	id: 'storage.sync',
+	name: 'sync',
+	description: 'Cloud synchronization for storage manifests',
+	parent: 'storage',
+	surfaces: ['cli'],
+	hardware: ['consumer'],
+	enabled: true
+};
+
+export default descriptor;

package/src/cli/types.ts

@@ -0,0 +1,25 @@
+/**
+ * Local CLI Types (storage)
+ *
+ * Storage's CLI command implementations consume the runtime context `cli/ui`,
+ * whose canonical shape lives in `@vibesdotdev/cli/providers`. To avoid a
+ * back-import on `@vibesdotdev/cli` (which itself depends on storage), this
+ * module declares a structural subset that matches the methods the storage
+ * commands actually use. The full UIContext lives in `@vibesdotdev/cli`.
+ */
+
+export interface StorageCliUIContext {
+	info(message: string): void;
+	success(message: string): void;
+	warn(message: string): void;
+	error(message: string): void;
+	log(message: string): void;
+	table(data: unknown[], options?: { columns?: string[] } | string | string[]): void;
+	json(data: unknown): void;
+	yaml(data: unknown): void;
+	keyValue(data: Record<string, unknown>): void;
+	render(
+		data: unknown,
+		options?: { format?: 'json' | 'yaml' | 'table' | 'markdown' | 'text' }
+	): void | Promise<void>;
+}

package/src/client/index.ts

@@ -0,0 +1,10 @@
+/**
+ * Storage Client Surface
+ *
+ * Consumer-facing query helpers that read storage runtime kinds —
+ * thin wrappers over `runtime.query('storage/adapter')`, exposed so
+ * UI/orchestration packages can build pickers without re-implementing
+ * the descriptor-shape understanding.
+ */
+
+export { listBrowsableStorageAdapters } from './list-browsable-adapters';

package/src/client/list-browsable-adapters.ts

@@ -0,0 +1,42 @@
+/**
+ * Browsable Storage Adapters Query Helper
+ *
+ * Thin wrapper over `runtime.query('storage/adapter')` that filters
+ * registered storage adapters down to the ones declaring the `'browse'`
+ * capability — i.e. adapters that implement `listDrives()` +
+ * `list(driveId, path)` and are therefore suitable for cloud-storage
+ * picker UIs (model sources, knowledge corpora, etc.).
+ *
+ * Lives in `@vibesdotdev/storage/client` because it is consumer-facing
+ * (UIs and orchestration code) — not part of the kind core. The helper
+ * does not load adapter implementations; it only inspects descriptors.
+ */
+
+import { getVibesRuntime } from '@vibesdotdev/runtime/api/runtime';
+import type { StorageAdapterDescriptor } from '../schemas/adapter-descriptor';
+
+/**
+ * Return every `storage/adapter` descriptor whose declared
+ * `capabilities[]` includes `'browse'`.
+ *
+ * Synchronous descriptor read — no implementation loading. Safe to call
+ * from server endpoints that build picker payloads.
+ *
+ * @example
+ * ```ts
+ * import { listBrowsableStorageAdapters } from '@vibesdotdev/storage/client';
+ *
+ * const browsable = listBrowsableStorageAdapters();
+ * // → [{ id: 'sharepoint', name: 'SharePoint Storage', ... }, ...]
+ * ```
+ */
+export function listBrowsableStorageAdapters(): StorageAdapterDescriptor[] {
+	const runtime = getVibesRuntime();
+	return runtime
+		.query('storage/adapter')
+		.filter((d) => {
+			const caps = (d as StorageAdapterDescriptor).capabilities;
+			return Array.isArray(caps) && caps.includes('browse');
+		})
+		.descriptors() as StorageAdapterDescriptor[];
+}