@vibesdotdev/storage 0.0.1

package/src/record/events.ts

@@ -0,0 +1,56 @@
+/**
+ * Storage Record Lifecycle Events
+ *
+ * Declares runtime/event descriptors for StorageRecord CRUD operations.
+ * These are automatically emitted by StorageRecord — no manual emission needed.
+ *
+ * Subscribe to these events via runtime/subscription descriptors:
+ * @example
+ * ```typescript
+ * createRuntimeAsset({
+ *   kind: 'runtime/subscription',
+ *   id: 'my-feature.on-record-created',
+ *   event: 'storage.record.afterCreate',
+ *   handler: 'my-feature.process-new-record',
+ *   filter: { recordKind: 'knowledge.items' }
+ * })
+ * ```
+ */
+
+import { createRuntimeAsset } from '@vibesdotdev/runtime';
+
+export const storageRecordCreatedEvent = createRuntimeAsset({
+	kind: 'runtime/event' as const,
+	id: 'storage.record.afterCreate',
+	name: 'Storage Record Created',
+	description: 'Emitted after a StorageRecord creates a new record',
+	trigger: 'lifecycle' as const,
+	source: 'storage/record',
+	lifecycle: 'afterCreate' as const
+});
+
+export const storageRecordUpdatedEvent = createRuntimeAsset({
+	kind: 'runtime/event' as const,
+	id: 'storage.record.afterUpdate',
+	name: 'Storage Record Updated',
+	description: 'Emitted after a StorageRecord updates an existing record',
+	trigger: 'lifecycle' as const,
+	source: 'storage/record',
+	lifecycle: 'afterUpdate' as const
+});
+
+export const storageRecordDeletedEvent = createRuntimeAsset({
+	kind: 'runtime/event' as const,
+	id: 'storage.record.afterDelete',
+	name: 'Storage Record Deleted',
+	description: 'Emitted after a StorageRecord deletes a record (soft or hard)',
+	trigger: 'lifecycle' as const,
+	source: 'storage/record',
+	lifecycle: 'afterDelete' as const
+});
+
+export const storageRecordEvents = [
+	storageRecordCreatedEvent,
+	storageRecordUpdatedEvent,
+	storageRecordDeletedEvent
+];

package/src/record/extensions.ts

@@ -0,0 +1,308 @@
+/**
+ * StorageRecord Extended Methods
+ *
+ * Additional methods for FTS, hierarchy, computed fields, side effects, and raw queries.
+ * These are mixed into the StorageRecord class.
+ */
+
+import type { SqlDatabaseHandle } from '../interfaces/adapter';
+import { getLogger } from '@vibesdotdev/logging';
+import { toErrorContext } from '../utils/error-context';
+
+import type { StorageRecordDescriptor, StorageSideEffect } from '../schemas/record';
+
+const logger = getLogger('storage:record');
+import type {
+	SearchOptions,
+	SearchResult,
+	HierarchyOptions,
+	TreeNode,
+	RawQueryOptions,
+	QueryOptions,
+	QueryResult
+} from '../interfaces/record';
+import type { VibesRuntime } from '@vibesdotdev/runtime';
+
+/**
+ * Extended StorageRecord methods interface
+ */
+export interface StorageRecordExtensions<T> {
+	// FTS
+	search(query: string, options?: SearchOptions<T>): Promise<SearchResult<T>>;
+
+	// Hierarchy
+	getDescendants(
+		id: string,
+		options?: HierarchyOptions<T>
+	): Promise<QueryResult<T & { depth: number; path?: string[] }>>;
+	getAncestors(id: string, options?: QueryOptions<T>): Promise<T[]>;
+	getTree(options?: HierarchyOptions<T>): Promise<TreeNode<T>[]>;
+
+	// Raw
+	raw<R>(sql: string, ...params: unknown[]): Promise<R[]>;
+	queryRaw<R>(options: RawQueryOptions<R>): Promise<R[]>;
+}
+
+/**
+ * Create FTS table and triggers for SQLite
+ */
+export function createFtsTable(
+	db: SqlDatabaseHandle,
+	tableName: string,
+	ftsFields: string[],
+	ftsTableName?: string,
+	tokenizer?: string
+): void {
+	const ftsTable = ftsTableName || `${tableName}_fts`;
+	const tokenizerConfig = tokenizer || 'unicode61';
+	const fields = ftsFields.join(', ');
+
+	db.exec(`
+		CREATE VIRTUAL TABLE IF NOT EXISTS ${ftsTable} USING fts5(
+			${fields},
+			content='${tableName}',
+			tokenize='${tokenizerConfig}'
+		)
+	`);
+
+	db.exec(`
+		CREATE TRIGGER IF NOT EXISTS ${tableName}_fts_insert AFTER INSERT ON ${tableName}
+		BEGIN
+			INSERT INTO ${ftsTable}(rowid, ${fields})
+			SELECT NEW.rowid, ${ftsFields.map((f) => `NEW.${f}`).join(', ')} 
+			FROM ${tableName} WHERE rowid = NEW.rowid;
+		END
+	`);
+
+	db.exec(`
+		CREATE TRIGGER IF NOT EXISTS ${tableName}_fts_delete AFTER DELETE ON ${tableName}
+		BEGIN
+			INSERT INTO ${ftsTable}(${ftsTable}, rowid, ${fields})
+			VALUES('delete', OLD.rowid, ${ftsFields.map(() => 'NULL').join(', ')});
+		END
+	`);
+
+	db.exec(`
+		CREATE TRIGGER IF NOT EXISTS ${tableName}_fts_update AFTER UPDATE ON ${tableName}
+		BEGIN
+			INSERT INTO ${ftsTable}(${ftsTable}, rowid, ${fields})
+			VALUES('delete', OLD.rowid, ${ftsFields.map(() => 'NULL').join(', ')});
+			INSERT INTO ${ftsTable}(rowid, ${fields})
+			SELECT NEW.rowid, ${ftsFields.map((f) => `NEW.${f}`).join(', ')}
+			FROM ${tableName} WHERE rowid = NEW.rowid;
+		END
+	`);
+}
+
+/**
+ * Build FTS search query for SQLite
+ */
+export function buildFtsSearchQuery(
+	tableName: string,
+	ftsFields: string[],
+	query: string,
+	options?: SearchOptions<unknown>
+): { sql: string; params: unknown[] } {
+	const ftsTable = `${tableName}_fts`;
+
+	const escapedQuery = `"${query.replace(/"/g, '""')}"`;
+
+	let sql = `
+		SELECT 
+			${tableName}.*,
+			${ftsTable}.rank as _rank
+		FROM ${tableName}
+		JOIN ${ftsTable} ON ${ftsTable}.rowid = ${tableName}.rowid
+		WHERE ${ftsTable} MATCH ?
+	`;
+
+	const params: unknown[] = [escapedQuery];
+
+	if (options?.where) {
+		const conditions = Object.entries(options.where).map(([field, value]) => {
+			params.push(value);
+			return `json_extract(${tableName}.data, '$.${field}') = ?`;
+		});
+		if (conditions.length > 0) {
+			sql += ` AND ${conditions.join(' AND ')}`;
+		}
+	}
+
+	if (options?.rankByRelevance !== false) {
+		sql += ` ORDER BY ${ftsTable}.rank`;
+	}
+
+	return { sql, params };
+}
+
+/**
+ * Build recursive CTE for hierarchy queries
+ */
+export function buildRecursiveCTE(
+	tableName: string,
+	parentField: string,
+	primaryKey: string,
+	rootId: string,
+	options?: HierarchyOptions<unknown>
+): { sql: string; params: unknown[] } {
+	const maxDepth = options?.maxDepth || 1000;
+	const includePath = options?.includePath !== false;
+
+	const pathArray = includePath
+		? `, CASE WHEN depth = 0 THEN json_array(id) ELSE json_insert(path, '$[#]', id) END`
+		: '';
+
+	const sql = `
+		WITH RECURSIVE hierarchy AS (
+			SELECT 
+				*,
+				0 as depth
+				${pathArray}
+			FROM ${tableName}
+			WHERE ${primaryKey} = ?
+			
+			UNION ALL
+			
+			SELECT 
+				t.*,
+				h.depth + 1 as depth
+				${pathArray}
+			FROM ${tableName} t
+			INNER JOIN hierarchy h ON t.${parentField} = h.${primaryKey}
+			WHERE h.depth < ?
+		)
+		SELECT * FROM hierarchy ORDER BY depth, ${primaryKey}
+	`;
+
+	return { sql, params: [rootId, maxDepth] };
+}
+
+/**
+ * Execute side effects
+ */
+export async function executeSideEffects(
+	sideEffects: StorageSideEffect[],
+	sourceRecord: Record<string, unknown>,
+	runtime?: VibesRuntime,
+	db?: SqlDatabaseHandle
+): Promise<void> {
+	for (const effect of sideEffects) {
+		try {
+			// Get target ID from foreign key
+			const targetId = effect.foreignKey ? sourceRecord[effect.foreignKey] : null;
+
+			if (!targetId && !effect.ignoreMissing) {
+				logger.warn(`[SideEffects] No target ID for effect on ${effect.target}`);
+				continue;
+			}
+
+			// Calculate value
+			let value: unknown;
+			if (effect.valueFn) {
+				value = (effect.valueFn as Function)(sourceRecord);
+			} else if (effect.value !== undefined) {
+				value = effect.value;
+			} else if (effect.operation === 'touch') {
+				value = new Date().toISOString();
+			}
+
+			// Execute update
+			if (db && targetId) {
+				const _setClause = effect.field ? `json_set(data, '$.${effect.field}', ?)` : '?';
+
+				if (effect.operation === 'increment' && effect.field) {
+					db.query(
+						`
+						UPDATE ${effect.target.split('.')[1] || effect.target} 
+						SET data = json_set(data, '$.${effect.field}', 
+							COALESCE(json_extract(data, '$.${effect.field}'), 0) + 1)
+						WHERE id = ?
+					`
+					).run(targetId as string);
+				} else if (effect.operation === 'decrement' && effect.field) {
+					db.query(
+						`
+						UPDATE ${effect.target.split('.')[1] || effect.target}
+						SET data = json_set(data, '$.${effect.field}',
+							COALESCE(json_extract(data, '$.${effect.field}'), 0) - 1)
+						WHERE id = ?
+					`
+					).run(targetId as string);
+				} else if (effect.field) {
+					db.query(
+						`
+						UPDATE ${effect.target.split('.')[1] || effect.target}
+						SET data = json_set(data, '$.${effect.field}', ?)
+						WHERE id = ?
+					`
+					).run(value as string, targetId as string);
+				}
+		}
+	} catch (error) {
+		logger.error(`[SideEffects] Failed to execute effect:`, toErrorContext(error));
+		if (!effect.ignoreMissing) {
+			throw error;
+		}
+		}
+	}
+}
+
+/**
+ * Build computed field subquery
+ */
+export function buildComputedFieldSubquery(
+	descriptor: StorageRecordDescriptor,
+	fieldName: string,
+	computedField: NonNullable<StorageRecordDescriptor['computedFields']>[string]
+): string {
+	const relation = descriptor.relations?.[computedField.relation];
+	if (!relation) return '0';
+
+	const targetTable = relation.target.split('.')[1] || relation.target;
+	const foreignKey = relation.foreignKey || `${descriptor.tableName.slice(0, -1)}_id`;
+
+	let aggregation: string;
+	switch (computedField.type) {
+		case 'count':
+			aggregation = 'COUNT(*)';
+			break;
+		case 'sum':
+			aggregation = computedField.field
+				? `SUM(CAST(json_extract(data, '$.${computedField.field}') AS REAL))`
+				: '0';
+			break;
+		case 'avg':
+			aggregation = computedField.field
+				? `AVG(CAST(json_extract(data, '$.${computedField.field}') AS REAL))`
+				: '0';
+			break;
+		case 'min':
+			aggregation = computedField.field
+				? `MIN(json_extract(data, '$.${computedField.field}'))`
+				: 'NULL';
+			break;
+		case 'max':
+			aggregation = computedField.field
+				? `MAX(json_extract(data, '$.${computedField.field}'))`
+				: 'NULL';
+			break;
+		case 'exists':
+			aggregation = 'CASE WHEN EXISTS(SELECT 1) THEN 1 ELSE 0 END';
+			break;
+		default:
+			aggregation = '0';
+	}
+
+	const whereClause = computedField.where
+		? Object.entries(computedField.where)
+				.map(([field, value]) => `json_extract(data, '$.${field}') = '${value}'`)
+				.join(' AND ')
+		: '';
+
+	return `(
+		SELECT ${aggregation}
+		FROM ${targetTable}
+		WHERE ${foreignKey} = ${descriptor.tableName}.${descriptor.primaryKey}
+		${whereClause ? `AND ${whereClause}` : ''}
+	) as ${fieldName}`;
+}

package/src/record/index.ts

@@ -0,0 +1,7 @@
+/**
+ * Storage Record Exports
+ *
+ * Exports the StorageRecord class for single-table CRUD operations.
+ */
+
+export { StorageRecord } from './base';

package/src/resolver/storage-backed-resolver.ts

@@ -0,0 +1,255 @@
+import type { RuntimeDescriptor } from '@vibesdotdev/runtime/schemas/descriptor';
+import type {
+	RuntimeResolverDescriptor,
+	RuntimeResolverFetchAllOptions,
+	RuntimeResolverFetchOptions,
+	RuntimeResolverInterface
+} from '@vibesdotdev/runtime/schemas/resolver';
+import type { StorageManifestDescriptor } from '../schemas/manifest-descriptor';
+import type { StorageKindBridgeConfig } from '../bridge/types';
+import type { KindContext } from '@vibesdotdev/runtime/schemas/kind';
+import { StorageManifest } from '../manifest/base';
+import {
+	resolveAdapterOrderBySource,
+	resolveScopeForSource,
+	resolveSourceFromAdapter,
+	type ManifestDataSource
+} from '../manifest/source-policy';
+
+interface SourcedManifestItem {
+	item: unknown;
+	source: ManifestDataSource | null;
+}
+
+type ManifestDescriptor = StorageManifestDescriptor;
+
+export class StorageBackedResolver implements RuntimeResolverInterface {
+	private readonly manifestId: string;
+	private readonly manifestKind: 'storage/manifest' | 'config/manifest';
+	private readonly targetKind: string;
+
+	constructor(
+		descriptor: RuntimeResolverDescriptor,
+		private context: KindContext
+	) {
+		this.manifestId = descriptor.manifestId;
+		this.manifestKind = descriptor.manifestKind ?? 'storage/manifest';
+		this.targetKind = descriptor.targetKind;
+	}
+
+	async fetch(
+		id: string,
+		options?: RuntimeResolverFetchOptions
+	): Promise<RuntimeDescriptor | null> {
+		const cached = options?.cache?.getDescriptors()?.find((descriptor: RuntimeDescriptor) => descriptor.id === id);
+		if (cached) return cached;
+
+		const bridgeConfig = this.getBridgeConfig();
+		if (!bridgeConfig) return null;
+
+		const items = await this.loadItems(bridgeConfig);
+		if (!items) return null;
+
+		let resolved: RuntimeDescriptor | null = null;
+		for (const sourced of items) {
+			if (bridgeConfig.filter && !bridgeConfig.filter(sourced.item)) continue;
+
+			const descriptor = bridgeConfig.toDescriptor(sourced.item);
+			if (descriptor.id === id) {
+				resolved = this.withRuntimeSource(descriptor, sourced.source);
+			}
+		}
+
+		if (resolved && options?.cache) {
+			const cacheLimit = options.maxCacheSize ?? 1000;
+			const descriptors = await this.fetchAll({ maxCacheSize: cacheLimit });
+			if (descriptors.length <= cacheLimit) options.cache.setDescriptors(descriptors);
+		}
+		return resolved;
+	}
+
+	async fetchAll(options?: RuntimeResolverFetchAllOptions): Promise<RuntimeDescriptor[]> {
+		const cached = options?.cache?.getDescriptors();
+		if (cached) return this.applyLimit(cached, options?.limit);
+
+		const bridgeConfig = this.getBridgeConfig();
+		if (!bridgeConfig) return [];
+
+		const items = await this.loadItems(bridgeConfig);
+		if (!items) return [];
+
+		const descriptorsById = new Map<string, RuntimeDescriptor>();
+		for (const sourced of items) {
+			if (bridgeConfig.filter && !bridgeConfig.filter(sourced.item)) continue;
+			const descriptor = bridgeConfig.toDescriptor(sourced.item);
+			descriptorsById.set(descriptor.id, this.withRuntimeSource(descriptor, sourced.source));
+		}
+		const descriptors = [...descriptorsById.values()];
+		const cacheLimit = options?.maxCacheSize ?? 1000;
+		if (options?.cache && descriptors.length <= cacheLimit) {
+			options.cache.setDescriptors(descriptors);
+		}
+		return this.applyLimit(descriptors, options?.limit);
+	}
+
+	private applyLimit(
+		descriptors: RuntimeDescriptor[],
+		limit: number | undefined
+	): RuntimeDescriptor[] {
+		if (!limit || limit < 1) return descriptors;
+		return descriptors.slice(0, limit);
+	}
+
+	private async loadItems(
+		_bridgeConfig: StorageKindBridgeConfig
+	): Promise<SourcedManifestItem[] | null> {
+		const manifestDescriptor = this.getManifestDescriptor();
+		if (!manifestDescriptor) return null;
+
+		const adapterIds = this.getOrderedAdapters(manifestDescriptor);
+		if (adapterIds.length === 0) return null;
+
+		const sourceData = await Promise.all(
+			adapterIds.map(async (adapterId) => ({
+				source: resolveSourceFromAdapter(adapterId),
+				data: await this.loadFromAdapter(manifestDescriptor, adapterId)
+			}))
+		);
+		const items = this.mergeSourcedItems(sourceData);
+		if (items.length === 0) return null;
+
+		return items;
+	}
+
+	private getManifestDescriptor(): ManifestDescriptor | null {
+		const runtime = this.context.runtime as {
+			hasKind(kind: string): boolean;
+			assets(kind: string): { descriptor(id: string): unknown };
+		};
+		if (!runtime.hasKind(this.manifestKind)) return null;
+
+		const descriptor = runtime.assets(this.manifestKind).descriptor(this.manifestId);
+		if (!descriptor || typeof descriptor !== 'object') return null;
+		return descriptor as ManifestDescriptor;
+	}
+
+	private getOrderedAdapters(descriptor: ManifestDescriptor): string[] {
+		return resolveAdapterOrderBySource(
+			Array.isArray(descriptor.allowedAdapters) ? descriptor.allowedAdapters : []
+		);
+	}
+
+	private async loadFromAdapter(
+		descriptor: ManifestDescriptor,
+		adapterId: string
+	): Promise<unknown | null> {
+		try {
+			const patched = this.patchDescriptorForAdapter(descriptor, adapterId);
+			const manifest = new StorageManifest(patched as StorageManifestDescriptor, this.context);
+			return await manifest.load();
+		} catch {
+			return null;
+		}
+	}
+
+	private patchDescriptorForAdapter(
+		descriptor: ManifestDescriptor,
+		adapterId: string
+	): ManifestDescriptor {
+		const source = resolveSourceFromAdapter(adapterId);
+		const allowedAdapters = [
+			adapterId,
+			...(descriptor.allowedAdapters ?? []).filter((id: string) => id !== adapterId)
+		];
+		const adapterConfig = { ...descriptor.adapterConfig };
+		if (adapterId === 'storage.json') {
+			const jsonConfig = adapterConfig['storage.json'];
+			if (!jsonConfig || typeof jsonConfig !== 'object') {
+				adapterConfig['storage.json'] = { filename: `${descriptor.namespace}.json` };
+			}
+		}
+		const scopePaths = descriptor.scopePaths ? { ...descriptor.scopePaths } : undefined;
+		if (source === 'project-file' && adapterId === 'storage.json') {
+			const nextScopePaths = scopePaths ?? {};
+			nextScopePaths.project = '{workspace}';
+			nextScopePaths.local = '{workspace}';
+			return {
+				...descriptor,
+				allowedAdapters,
+				defaultAdapter: adapterId,
+				scope: resolveScopeForSource(source, descriptor.scope),
+				scopePaths: nextScopePaths,
+				adapterConfig
+			} as ManifestDescriptor;
+		}
+		return {
+			...descriptor,
+			allowedAdapters,
+			defaultAdapter: adapterId,
+			scope: source ? resolveScopeForSource(source, descriptor.scope) : descriptor.scope,
+			scopePaths,
+			adapterConfig
+		} as ManifestDescriptor;
+	}
+
+	private mergeSourcedItems(
+		values: Array<{ source: ManifestDataSource | null; data: unknown | null }>
+	): SourcedManifestItem[] {
+		const byId = new Map<string, SourcedManifestItem>();
+		const loose: SourcedManifestItem[] = [];
+
+		for (const entry of values) {
+			if (entry.data === null || entry.data === undefined) continue;
+			for (const item of this.asItems(entry.data)) {
+				if (item && typeof item === 'object' && typeof (item as { id?: unknown }).id === 'string') {
+					const id = (item as { id: string }).id;
+					if (!byId.has(id)) byId.set(id, { item, source: entry.source });
+					continue;
+				}
+				loose.push({ item, source: entry.source });
+			}
+		}
+
+		return [...loose, ...byId.values()];
+	}
+
+	private asItems(data: unknown): unknown[] {
+		if (!data) return [];
+		if (Array.isArray(data)) return data;
+		if (typeof data === 'object' && data !== null && data.constructor === Object) {
+			return Object.values(data);
+		}
+		return [data];
+	}
+
+	private withRuntimeSource(
+		descriptor: RuntimeDescriptor,
+		source: ManifestDataSource | null
+	): RuntimeDescriptor {
+		if (!source) return descriptor;
+		return Object.assign({}, descriptor, { runtimeSource: source }) as RuntimeDescriptor;
+	}
+
+	private getBridgeConfig(): StorageKindBridgeConfig | null {
+		const runtime = this.context.runtime as {
+			hasKind(kind: string): boolean;
+			assets(kind: string): {
+				descriptor(id: string): StorageManifestDescriptor | undefined;
+			};
+		};
+
+		if (!runtime.hasKind(this.manifestKind)) return null;
+
+		const manifestDescriptor = runtime.assets(this.manifestKind).descriptor(this.manifestId) as
+			| StorageManifestDescriptor
+			| undefined;
+
+		if (!manifestDescriptor?.providesRuntimeKinds) return null;
+
+		return (
+			(manifestDescriptor.providesRuntimeKinds as Record<string, StorageKindBridgeConfig>)[
+				this.targetKind
+			] ?? null
+		);
+	}
+}