@vibesdotdev/storage 0.0.1

package/src/schemas/adapter-descriptor.ts

@@ -0,0 +1,128 @@
+/**
+ * Storage Adapter Descriptor Schema
+ *
+ * Schema for storage/adapter kind descriptors.
+ * Extends base descriptor with storage-specific fields.
+ */
+
+import * as z from 'zod/v4';
+import { RuntimeDescriptorSchema } from '@vibesdotdev/runtime/schemas/descriptor';
+
+/**
+ * Storage protocols supported by adapters
+ */
+export const StorageProtocolSchema = z.enum(['document', 'keyvalue', 'repository', 'record']);
+
+/**
+ * Coarse-grained adapter capabilities surfaced to consumers.
+ *
+ * - `list`   — adapter can enumerate items in a container (document protocol's `list()`).
+ * - `read`   — adapter can read existing items.
+ * - `write`  — adapter can create / update / delete items.
+ * - `browse` — adapter implements `list(driveId, path) → StorageEntry[]` and
+ *              `listDrives() → StorageDrive[]` for foldered cloud-storage browsing
+ *              (SharePoint, OneDrive, Google Drive, etc.). Consumers like the
+ *              AI model-source picker filter on this capability to surface
+ *              browsable backends.
+ */
+export const StorageCapabilitySchema = z.enum(['list', 'read', 'write', 'browse']);
+
+/**
+ * Storage adapter descriptor schema
+ */
+export const StorageAdapterDescriptorSchema = RuntimeDescriptorSchema.extend({
+	kind: z.literal('storage/adapter'),
+
+	/** Storage protocols supported by this adapter */
+	protocols: z.array(StorageProtocolSchema),
+
+	/**
+	 * Coarse-grained capability flags consumed by clients that
+	 * want to filter adapters by what they can do. `browse` implies the
+	 * adapter implements `list(driveId, path)` + `listDrives()`.
+	 */
+	capabilities: z.array(StorageCapabilitySchema).default(['read', 'write']),
+
+	/** Whether adapter requires pair schema (key + value) for main storage */
+	requiresPairSchema: z.boolean().default(false),
+
+	/** Whether adapter supports transactions */
+	supportsTransactions: z.boolean().default(false),
+
+	/** Whether adapter supports TTL (for caches) */
+	supportsTTL: z.boolean().default(false),
+
+	/** Whether adapter supports full-text search */
+	supportsSearch: z.boolean().default(false),
+
+	/** Whether adapter supports full-text search (alias for supportsSearch) */
+	supportsFTS: z.boolean().default(false),
+
+	/** Whether adapter is persistent (survives restarts) */
+	persistent: z.boolean().default(false),
+
+	/** Whether adapter supports change subscriptions */
+	supportsSubscription: z.boolean().default(false),
+
+	/** Whether adapter supports hierarchical/recursive queries */
+	supportsHierarchy: z.boolean().default(false),
+
+	/** Whether adapter supports computed fields (aggregations) */
+	supportsComputedFields: z.boolean().default(false),
+
+	/** Whether adapter supports cross-table side effects */
+	supportsSideEffects: z.boolean().default(false),
+
+	/** Whether adapter supports raw SQL queries */
+	supportsRawQueries: z.boolean().default(false)
+});
+
+export type StorageProtocol = z.infer<typeof StorageProtocolSchema>;
+export type StorageCapability = z.infer<typeof StorageCapabilitySchema>;
+export type StorageAdapterDescriptor = z.infer<typeof StorageAdapterDescriptorSchema>;
+
+// Browse — drive + entry shapes for `browse`-capable adapters
+
+/**
+ * A logical "drive" inside a browsable storage adapter — a top-level
+ * container the consumer picks before drilling into folders.
+ *
+ * For SharePoint: a `site`. For OneDrive: the user's default drive.
+ * For Google Drive (future): a "My Drive" or "Shared Drive" entry.
+ *
+ * Returned by `adapter.listDrives()`.
+ */
+export const StorageDriveSchema = z.object({
+	/** Stable provider-side identifier for the drive (site id, drive id, etc.). */
+	id: z.string(),
+	/** Human-readable name. */
+	name: z.string(),
+	/**
+	 * Provider-specific drive kind. Free-form by design — consumers do
+	 * not match on this. Example values: `'site'`, `'drive'`, `'shared'`.
+	 */
+	kind: z.string()
+});
+
+export type StorageDrive = z.infer<typeof StorageDriveSchema>;
+
+/**
+ * A single entry returned by `adapter.list(driveId, path)` —
+ * a file or directory inside a browsable storage adapter.
+ */
+export const StorageEntrySchema = z.object({
+	/** Stable provider-side identifier (drive item id, blob id, etc.). */
+	id: z.string(),
+	/** Display name (e.g. `Quarterly Report.pdf`). */
+	name: z.string(),
+	/** Path relative to the drive root, including the entry's own name. */
+	path: z.string(),
+	/** File vs directory discriminator. */
+	kind: z.enum(['file', 'directory']),
+	/** Size in bytes when known (directories omit this). */
+	sizeBytes: z.number().int().optional(),
+	/** Last modified timestamp (ISO 8601, when known). */
+	modifiedAt: z.string().optional()
+});
+
+export type StorageEntry = z.infer<typeof StorageEntrySchema>;

package/src/schemas/index.ts

@@ -0,0 +1,104 @@
+/**
+ * Storage Schemas
+ *
+ * Export all storage-related schemas and types.
+ */
+
+export {
+	StorageProtocolSchema,
+	StorageCapabilitySchema,
+	StorageAdapterDescriptorSchema,
+	StorageDriveSchema,
+	StorageEntrySchema
+} from './adapter-descriptor';
+
+export type {
+	StorageProtocol,
+	StorageCapability,
+	StorageAdapterDescriptor,
+	StorageDrive,
+	StorageEntry
+} from './adapter-descriptor';
+
+export {
+	StorageScopeSchema,
+	StorageDataTypeSchema,
+	StorageCloudApiAdapterConfigSchema,
+	StorageManifestDescriptorSchema,
+} from './manifest-descriptor';
+
+export type {
+	StorageScope,
+	StorageDataType,
+	StorageCloudApiAdapterConfig,
+	StorageManifestDescriptor
+} from './manifest-descriptor';
+
+// Storage record kind (single table CRUD operations)
+export {
+	StorageRecordDescriptorSchema,
+	StorageSyncConfigSchema,
+	StorageRemoteCrudSchema,
+	StorageRemoteConfigSchema,
+	StoragePersistenceModeSchema,
+	StoragePersistencePolicySchema,
+	StorageOwnershipFilterSchema,
+	StorageRelationTypeSchema,
+	StorageRelationSchema,
+	StorageIndexSchema,
+	StorageMigrationSchema,
+	StorageFieldConfigSchema,
+	StorageFtsConfigSchema,
+	StorageComputedFieldSchema,
+	StorageHierarchyConfigSchema,
+	StorageSideEffectOperationSchema,
+	StorageSideEffectSchema,
+	StorageSideEffectsConfigSchema
+} from './record';
+
+export type {
+	StorageRecordDescriptor,
+	StorageRecordDescriptorInput,
+	StorageSyncConfig,
+	StorageRemoteCrud,
+	StorageRemoteConfig,
+	StoragePersistenceMode,
+	StoragePersistencePolicy,
+	StorageOwnershipFilter,
+	StorageSyncContext,
+	StorageRecordLocalSyncContext,
+	StorageRecordRemoteSyncContext,
+	StorageRecordSyncHooks,
+	StorageRelationType,
+	StorageRelation,
+	StorageIndex,
+	StorageIndexInput,
+	StorageMigration,
+	StorageMigrationInput,
+	StorageFieldConfig,
+	StorageFieldConfigInput,
+	StorageFtsConfig,
+	StorageFtsConfigInput,
+	StorageComputedField,
+	StorageComputedFieldInput,
+	StorageHierarchyConfig,
+	StorageHierarchyConfigInput,
+	StorageSideEffectOperation,
+	StorageSideEffect,
+	StorageSideEffectInput,
+	StorageSideEffectsConfig,
+	StorageSideEffectsConfigInput
+} from './record';
+
+// Storage schema kind (multi-table schemas with relations)
+export {
+	StorageSchemaDescriptorSchema,
+	StorageTableDefinitionSchema,
+	MigrationSourceSchema
+} from './schema';
+
+export type {
+	StorageSchemaDescriptor,
+	StorageTableDefinition,
+	MigrationSource
+} from './schema';

package/src/schemas/manifest-descriptor.ts

@@ -0,0 +1,143 @@
+/**
+ * Storage Manifest Descriptor Schema
+ *
+ * Schema for storage/manifest kind descriptors.
+ * Describes a data type that can be stored.
+ */
+
+import * as z from 'zod/v4';
+import { RuntimeDescriptorSchema } from '@vibesdotdev/runtime/schemas/descriptor';
+
+/**
+ * Storage scope for path resolution
+ */
+export const StorageScopeSchema = z.enum(['global', 'project', 'local', 'auto']);
+
+/**
+ * Canonical storage data shape.
+ *
+ * - raw: keyed raw text values
+ * - records: structured row collection with CRUD semantics
+ * - objects: keyed JSON/blob objects or a whole document object
+ */
+export const StorageDataTypeSchema = z.enum(['raw', 'records', 'objects']);
+
+/**
+ * Per-scope path configuration
+ * Allows manifests to customize base paths for each scope
+ */
+export const ScopePathConfigSchema = z
+	.object({
+		global: z.string().optional(),
+		project: z.string().optional(),
+		local: z.string().optional()
+	})
+	.optional();
+
+/**
+ * Adapter-specific configuration
+ * Each adapter can define its own config shape
+ *
+ * Examples:
+ * - storage.drizzle: { tableName: 'ai_models', transforms: { toDb, fromDb } }
+ * - storage.localdb: { tableName: 'ai_models', createTable: 'CREATE TABLE...', dbName: 'custom.db', migrationKey: 'my-migrations' }
+ * - storage.json: { filename: 'ai-models.json' }
+ * - storage.cloud-api: { endpoint: '/api/models', ownerApp: 'ai' }
+ */
+export const StorageAdapterConfigSchema = z.record(z.string(), z.unknown());
+
+export const StorageCloudApiAdapterConfigSchema = z.object({
+	/** Owning app id used to resolve the base origin from config/environment.apps. */
+	ownerApp: z.string().optional(),
+	/** Canonical collection endpoint on the owning app, e.g. /api/providers. */
+	endpoint: z.string().optional(),
+	/** Optional explicit base origin, e.g. https://ai.vibes.dev. */
+	apiEndpoint: z.string().optional(),
+	/** Field that uniquely identifies records/objects in collection responses. */
+	idField: z.string().default('id'),
+	/** Declared transform ids. Runtime functions live in storage/transform. */
+	transform: z
+		.object({
+			from: z.string().optional(),
+			to: z.string().optional()
+		})
+		.optional()
+});
+
+/**
+ * Storage manifest descriptor schema
+ */
+export const StorageManifestDescriptorSchema = RuntimeDescriptorSchema.extend({
+	kind: z.literal('storage/manifest'),
+
+	/** Storage namespace (e.g., 'ai.providers', 'session') */
+	namespace: z.string().min(1),
+
+	/** Zod schema for the stored data (stored as unknown, validated at runtime) */
+	schema: z.unknown(),
+
+	/** Canonical storage data shape. Omitted legacy descriptors are treated as objects. */
+	dataType: StorageDataTypeSchema.optional(),
+
+	/** Field that uniquely identifies items for records/object collections. */
+	idField: z.string().default('id').optional(),
+
+	/** Optional field containing the record collection inside a state object. */
+	collectionField: z.string().optional(),
+
+	/** Allowed adapter IDs (e.g., ['storage.localdb', 'storage.json']) */
+	allowedAdapters: z.array(z.string()).min(1),
+
+	/** Default adapter to use when not specified */
+	defaultAdapter: z.string().optional(),
+
+	/** Adapter-specific configuration (e.g., table names, transforms, filenames) */
+	adapterConfig: StorageAdapterConfigSchema.optional(),
+
+	/** Storage scope for path resolution */
+	scope: StorageScopeSchema.default('auto'),
+
+	/** Custom base paths for each scope (overrides default scope paths) */
+	scopePaths: ScopePathConfigSchema,
+
+	/** Fields that require encryption (dot paths, e.g., 'apiKey', 'credentials.token') */
+	sensitiveFields: z.array(z.string()).optional(),
+
+	/** Whether this manifest uses custom tables instead of generic document storage */
+	customTables: z.boolean().default(false),
+
+	/** Migration key for custom tables (required if customTables = true) */
+	migrationKey: z.string().optional(),
+
+	/** Version for migrations (default: 1) */
+	version: z.number().int().positive().default(1),
+
+	/** Whether this manifest is internal (not user-editable) */
+	internal: z.boolean().default(false),
+
+	/**
+	 * ID of the corresponding config/manifest that stores the same data shape.
+	 *
+	 * When set, the save routing layer can pick the correct manifest kind based
+	 * on the target adapter: custom tables (localdb) use the storage/manifest,
+	 * while file/cloud targets use the config/manifest.
+	 */
+	configManifestId: z.string().optional(),
+
+	/**
+	 * Declares that items in this storage can source runtime kind queries.
+	 *
+	 * Keys are kind IDs (e.g., 'ai/agent', 'tools/tool').
+	 * Values are StorageKindBridgeConfig objects with toDescriptor, implementation, and filter.
+	 * Stored as z.unknown() because the config contains functions.
+	 *
+	 * @see StorageKindBridgeConfig in storage/bridge/types.ts
+	 */
+	providesRuntimeKinds: z.record(z.string(), z.unknown()).optional()
+});
+
+export type StorageScope = z.infer<typeof StorageScopeSchema>;
+export type StorageDataType = z.infer<typeof StorageDataTypeSchema>;
+export type ScopePathConfig = z.infer<typeof ScopePathConfigSchema>;
+export type StorageCloudApiAdapterConfig = z.infer<typeof StorageCloudApiAdapterConfigSchema>;
+export type StorageManifestDescriptor = z.infer<typeof StorageManifestDescriptorSchema>;