@vibesdotdev/storage 0.0.1

package/src/schemas/record/relation.ts

@@ -0,0 +1,49 @@
+/**
+ * Storage record relation schemas / types.
+ *
+ * Extracted from `./descriptor.ts` so the record interface module
+ * (`../../interfaces/record/interface.ts`) can reference `StorageRelation`
+ * without forming a cycle (descriptor.ts itself imports
+ * `StorageRecordInterface` from the interface module for its sync /
+ * remote context types).
+ */
+
+import * as z from 'zod/v4';
+
+/** Relation types for storage records. */
+export const StorageRelationTypeSchema = z.enum([
+	'belongs_to', // Many-to-one (e.g., todo belongs to session)
+	'has_one', // One-to-one (e.g., session has one config)
+	'has_many', // One-to-many (e.g., session has many todos)
+	'many_to_many' // Many-to-many (e.g., user has many roles)
+]);
+
+/** Relation definition for a storage record. */
+export const StorageRelationSchema = z.object({
+	/** Relation type */
+	type: StorageRelationTypeSchema,
+
+	/** Target record descriptor ID (e.g., 'session.sessions') */
+	target: z.string(),
+
+	/** Foreign key field in this table (for belongs_to) */
+	foreignKey: z.string().optional(),
+
+	/** Foreign key field in target table (for has_one/has_many) */
+	foreignKeyTarget: z.string().optional(),
+
+	/** Junction table for many_to_many relations */
+	through: z.string().optional(),
+
+	/** Whether this relation is optional */
+	optional: z.boolean().default(false),
+
+	/** Cascade delete when parent is deleted */
+	cascadeDelete: z.boolean().default(false),
+
+	/** Custom relation name (defaults to property key) */
+	as: z.string().optional()
+});
+
+export type StorageRelationType = z.infer<typeof StorageRelationTypeSchema>;
+export type StorageRelation = z.infer<typeof StorageRelationSchema>;

package/src/schemas/schema/descriptor.ts

@@ -0,0 +1,278 @@
+/**
+ * Storage Schema Descriptor Schema
+ *
+ * Defines a multi-table schema with relations for complex modules.
+ * Used for modules that need multiple related tables with foreign keys.
+ *
+ * @example
+ * ```typescript
+ * const sessionSchemaDescriptor: StorageSchemaDescriptor = {
+ *   kind: 'storage/schema',
+ *   id: 'session',
+ *   name: 'Session Storage Schema',
+ *   description: 'Complete session storage with multiple related tables',
+ *   tables: {
+ *     sessions: {
+ *       schema: SessionSchema,
+ *       primaryKey: 'id',
+ *       indexes: [{ fields: ['status'] }]
+ *     },
+ *     todos: {
+ *       schema: TodoSchema,
+ *       primaryKey: 'id',
+ *       relations: {
+ *         session: { type: 'belongs_to', target: 'sessions', foreignKey: 'sessionId' }
+ *       }
+ *     }
+ *   },
+ *   migrations: () => import('./migrations').then(m => m.SESSION_MIGRATIONS),
+ *   allowedAdapters: ['storage.localdb'],
+ *   dbName: 'sessions.db'
+ * };
+ * ```
+ */
+
+import * as z from 'zod/v4';
+import { RuntimeDescriptorSchema } from '@vibesdotdev/runtime/schemas/descriptor';
+import { StorageScopeSchema } from '../manifest-descriptor';
+import {
+	StorageRelationSchema,
+	StorageIndexSchema,
+	StorageMigrationSchema,
+	StorageFieldConfigSchema
+} from '../record/descriptor';
+
+/**
+ * Table definition within a schema
+ */
+export const StorageTableDefinitionSchema = z.object({
+	/** Zod schema for the table data (stored as unknown, validated at runtime) */
+	schema: z.unknown(),
+
+	/** Primary key field name (default: 'id') */
+	primaryKey: z.string().default('id'),
+
+	/** Relations to other tables in this schema */
+	relations: z.record(z.string(), StorageRelationSchema).optional(),
+
+	/** Database indexes for this table */
+	indexes: z.array(StorageIndexSchema).default([]),
+
+	/** Auto-manage timestamps (createdAt, updatedAt) */
+	timestamps: z
+		.union([
+			z.boolean(),
+			z.object({
+				createdAt: z.union([z.boolean(), z.string()]).optional(),
+				updatedAt: z.union([z.boolean(), z.string()]).optional()
+			})
+		])
+		.default(true),
+
+	/** Auto-generate IDs */
+	autoId: z
+		.union([
+			z.boolean(),
+			z.object({
+				field: z.string().optional(),
+				strategy: z.enum(['uuid', 'nanoid', 'custom']).optional(),
+				generator: z.optional(z.unknown())
+			})
+		])
+		.default(true),
+
+	/** Soft delete field (e.g., 'deletedAt') */
+	softDelete: z.union([z.boolean(), z.string()]).optional(),
+
+	/** Field-specific configurations */
+	fieldConfig: z.record(z.string(), StorageFieldConfigSchema).optional(),
+
+	/** Enable record versioning for optimistic locking */
+	versioning: z.boolean().default(false),
+
+	/** Enable audit trail (createdBy, updatedBy) */
+	audit: z.boolean().default(false),
+
+	/** Enable change tracking for sync */
+	changeTracking: z.boolean().default(false),
+
+	/** Custom validation function */
+	validate: z.optional(z.unknown()),
+
+	/** Before create hook */
+	beforeCreate: z.optional(z.unknown()),
+
+	/** After create hook */
+	afterCreate: z.optional(z.unknown()),
+
+	/** Before update hook */
+	beforeUpdate: z.optional(z.unknown()),
+
+	/** After update hook */
+	afterUpdate: z.optional(z.unknown()),
+
+	/** Before delete hook */
+	beforeDelete: z.optional(z.unknown()),
+
+	/** After delete hook */
+	afterDelete: z.optional(z.unknown())
+});
+
+/**
+ * Migration source - can be inline or lazy-loaded
+ */
+export const MigrationSourceSchema = z.union([
+	// Inline migrations array
+	z.array(StorageMigrationSchema),
+	// Lazy-loaded migrations (function that returns promise)
+	z.unknown(),
+	// Module import path
+	z.string()
+]);
+
+/**
+ * Storage schema descriptor schema
+ */
+export const StorageSchemaDescriptorSchema = RuntimeDescriptorSchema.extend({
+	kind: z.literal('storage/schema'),
+
+	// SCHEMA DEFINITION
+
+	/** Human-readable name */
+	name: z.string().min(1),
+
+	/** Human-readable description */
+	description: z.string().optional(),
+
+	/** Table definitions (key is table name) */
+	tables: z
+		.record(z.string(), StorageTableDefinitionSchema)
+		.refine((tables) => Object.keys(tables).length > 0, {
+			message: 'Schema must have at least one table'
+		}),
+
+	// MIGRATIONS
+
+	/** Inline or lazy-loaded migrations for this schema */
+	migrations: MigrationSourceSchema.optional(),
+
+	/** Migration key for external migrations (e.g., 'session') */
+	migrationKey: z.string().optional(),
+
+	/** Current schema version (default: 1) */
+	version: z.number().int().positive().default(1),
+
+	// ADAPTER SELECTION
+
+	/** Allowed adapter IDs (e.g., ['storage.localdb', 'storage.drizzle']) */
+	allowedAdapters: z.array(z.string()).min(1),
+
+	/** Default adapter to use when not specified */
+	defaultAdapter: z.string().optional(),
+
+	/** Adapter-specific configuration */
+	adapterConfig: z.record(z.string(), z.unknown()).optional(),
+
+	// SCOPE & STORAGE
+
+	/** Storage scope for path resolution */
+	scope: StorageScopeSchema.default('project'),
+
+	/** Custom database name (overrides default) */
+	dbName: z.string().optional(),
+
+	/** Database schema name (for Postgres) */
+	dbSchema: z.string().optional(),
+
+	/** Custom base path for database */
+	basePath: z.string().optional(),
+
+	// SCHEMA FEATURES
+
+	/** Enable foreign key constraints */
+	foreignKeys: z.boolean().default(true),
+
+	/** Enable cascade delete for relations with cascadeDelete=true */
+	cascadeDelete: z.boolean().default(true),
+
+	/** Enable transactions for multi-table operations */
+	transactions: z.boolean().default(true),
+
+	/** Enable database connection pooling */
+	pooling: z.boolean().default(true),
+
+	/** Pool size (if pooling enabled) */
+	poolSize: z.number().int().positive().default(5),
+
+	// SYNC & REPLICATION
+
+	/** Enable sync between runtimes */
+	sync: z.boolean().default(false),
+
+	/** Sync configuration */
+	syncConfig: z
+		.object({
+			/** Sync direction */
+			direction: z.enum(['bidirectional', 'to-cloud', 'from-cloud']).default('bidirectional'),
+
+			/** Conflict resolution strategy */
+			conflictResolution: z
+				.enum(['server-wins', 'client-wins', 'timestamp', 'custom'])
+				.default('timestamp'),
+
+			/** Custom conflict resolver */
+			conflictResolver: z.optional(z.unknown()),
+
+			/** Sync interval in milliseconds */
+			interval: z.number().int().positive().default(60000),
+
+			/** Tables to exclude from sync */
+			excludeTables: z.array(z.string()).optional()
+		})
+		.optional(),
+
+	// BACKUP & RESTORE
+
+	/** Enable automatic backups */
+	backup: z.boolean().default(false),
+
+	/** Backup configuration */
+	backupConfig: z
+		.object({
+			/** Backup interval in milliseconds */
+			interval: z.number().int().positive().default(86400000), // 24 hours
+
+			/** Maximum number of backups to keep */
+			maxBackups: z.number().int().positive().default(7),
+
+			/** Backup location */
+			location: z.string().optional(),
+
+			/** Tables to exclude from backup */
+			excludeTables: z.array(z.string()).optional()
+		})
+		.optional(),
+
+	// METADATA
+
+	/** Whether this schema is internal (not user-editable) */
+	internal: z.boolean().default(false),
+
+	/** Schema namespace (e.g., 'session') */
+	namespace: z.string().optional(),
+
+	/** Tags for categorization */
+	tags: z.array(z.string()).default([]),
+
+	/** Schema author/maintainer */
+	author: z.string().optional(),
+
+	/** Schema version history URL */
+	versionHistoryUrl: z.string().optional()
+});
+
+// TYPE EXPORTS
+
+export type StorageTableDefinition = z.infer<typeof StorageTableDefinitionSchema>;
+export type MigrationSource = z.infer<typeof MigrationSourceSchema>;
+export type StorageSchemaDescriptor = z.infer<typeof StorageSchemaDescriptorSchema>;

package/src/schemas/schema/index.ts

@@ -0,0 +1,14 @@
+/**
+ * Storage Schema Exports
+ *
+ * Exports all types and schemas for storage/schema descriptors.
+ */
+
+export {
+	StorageSchemaDescriptorSchema,
+	StorageTableDefinitionSchema,
+	MigrationSourceSchema,
+	type StorageSchemaDescriptor,
+	type StorageTableDefinition,
+	type MigrationSource
+} from './descriptor';

package/src/schemas/sync-bridge-descriptor.ts

@@ -0,0 +1,143 @@
+/**
+ * Storage Sync-Bridge Descriptor Schema
+ *
+ * Declares a bidirectional sync bridge between a runtime kind (local descriptors)
+ * and a cloud CRUD API. Replaces hand-rolled per-module sync services with a
+ * declarative descriptor that the generic sync executor can process.
+ *
+ * The bridge maps local runtime descriptors ↔ remote API records, handling
+ * ID transformation, ownership filtering, secret stripping, and conflict resolution.
+ */
+
+import * as z from 'zod/v4';
+import { RuntimeDescriptorSchema } from '@vibesdotdev/runtime/schemas/descriptor';
+
+export const SyncDirectionSchema = z.enum(['bidirectional', 'push-only', 'pull-only']);
+export type SyncDirection = z.infer<typeof SyncDirectionSchema>;
+
+export const ConflictStrategySchema = z.enum(['local-wins', 'remote-wins', 'manual', 'newest']);
+export type ConflictStrategy = z.infer<typeof ConflictStrategySchema>;
+
+export const OwnershipFilterSchema = z.enum(['all', 'user-only', 'system-only']);
+export type OwnershipFilter = z.infer<typeof OwnershipFilterSchema>;
+
+/**
+ * Schema for a sync-bridge descriptor.
+ *
+ * Extends RuntimeDescriptor with source/target/sync configuration.
+ */
+export const SyncBridgeDescriptorSchema = RuntimeDescriptorSchema.extend({
+	kind: z.literal('storage/sync-bridge'),
+
+	/** Source: where descriptors live locally */
+	source: z.object({
+		/** The runtime kind ID to collect descriptors from (e.g. 'dev/benchmark-suite') */
+		runtimeKind: z.string().min(1),
+
+		/** Optional: field on the descriptor that holds the version number */
+		versionField: z.string().optional(),
+
+		/** Optional: field on the descriptor that holds the source type ('system' | 'user') */
+		sourceTypeField: z.string().optional()
+	}),
+
+	/** Target: the cloud CRUD API to sync against */
+	target: z.object({
+		/** API path for the collection endpoint (e.g. '/api/dev/benchmarks') */
+		apiPath: z.string().min(1),
+
+		/** API path for a single entity, with :id placeholder (e.g. '/api/dev/benchmarks/:id') */
+		entityPath: z.string().optional(),
+
+		/** The field name in API responses that contains the list of items */
+		listField: z.string().optional(),
+
+		/** The field name for the total count in list responses */
+		totalField: z.string().optional(),
+
+		/** Request soft-deleted rows when the remote API supports it */
+		includeDeleted: z.boolean().optional()
+	}),
+
+	/** Sync behavior configuration */
+	sync: z
+		.object({
+			/** Sync direction */
+			direction: SyncDirectionSchema.default('bidirectional'),
+
+			/** Which entities to sync based on ownership */
+			ownershipFilter: OwnershipFilterSchema.default('all'),
+
+			/** How to handle conflicts when both sides changed */
+			conflictStrategy: ConflictStrategySchema.default('local-wins'),
+
+			/** Fields to strip before pushing to cloud (e.g. secrets) */
+			sensitiveFields: z.array(z.string()).default([]),
+
+			/** The field that uniquely identifies an entity */
+			idField: z.string().default('id')
+		})
+		.default({
+			direction: 'bidirectional',
+			ownershipFilter: 'all',
+			conflictStrategy: 'local-wins',
+			sensitiveFields: [],
+			idField: 'id'
+		})
+}).passthrough();
+
+export type SyncBridgeDescriptor = z.infer<typeof SyncBridgeDescriptorSchema> & {
+	/**
+	 * Transform a local runtime descriptor into the shape the API expects.
+	 * Called before pushing to cloud.
+	 */
+	toRemote?: (descriptor: Record<string, unknown>) => Record<string, unknown>;
+
+	/**
+	 * Transform an API response record into a local runtime descriptor shape.
+	 * Called after pulling from cloud.
+	 */
+	fromRemote?: (record: Record<string, unknown>) => Record<string, unknown>;
+
+	/**
+	 * Optional: Ensure remote prerequisites exist before pushing an entity.
+	 * Useful when the remote API expects related resources (for example, a
+	 * knowledge base) to exist before an item can be upserted.
+	 */
+	beforePush?: (
+		descriptor: Record<string, unknown>,
+		context: {
+			apiEndpoint: string;
+			apiToken?: string;
+			fetch: (input: string, init?: RequestInit) => Promise<Response>;
+		}
+	) => Promise<void>;
+
+	deleteRemote?: (
+		descriptor: Record<string, unknown>,
+		context: {
+			apiEndpoint: string;
+			apiToken?: string;
+			fetch: (input: string, init?: RequestInit) => Promise<Response>;
+		}
+	) => Promise<void>;
+
+	/**
+	 * Optional: Custom collection function. Defaults to runtime.query(source.runtimeKind).descriptors()
+	 */
+	collect?: () => Promise<Record<string, unknown>[]> | Record<string, unknown>[];
+
+	/**
+	 * Optional: Storage manifest ID for persisting pulled items.
+	 * When set, pulled items are merged into this storage manifest (localdb/json).
+	 * When omitted, pulled items are only registered with the runtime (descriptor-only bridges).
+	 */
+	storageManifestId?: string;
+
+	/**
+	 * Optional: Custom write function for pulled items.
+	 * Called when a remote-only item needs to be persisted locally.
+	 * When omitted and storageManifestId is set, uses StorageManifest.load/save.
+	 */
+	writePulled?: (items: Record<string, unknown>[]) => Promise<void>;
+};