@vibesdotdev/storage 0.0.1

package/src/interfaces/adapter.ts

@@ -0,0 +1,451 @@
+/**
+ * Storage Adapter Interface
+ *
+ * Main interface for storage adapters. Adapters provide access to
+ * document stores, key-value stores, repositories, and records.
+ *
+ * Each adapter can specify its own config type and declare which
+ * storage protocols and features it supports.
+ */
+
+import type { z } from 'zod/v4';
+import type { StorageDocumentStoreInterface } from './document-store';
+import type { StorageKeyValueInterface } from './key-value';
+import type { StorageRepositoryInterface, RepositoryOptions } from './repository';
+import type { StorageRecordInterface } from './record';
+import type { StorageRecordDescriptor } from '../schemas/record';
+import type { StorageCapability, StorageDrive, StorageEntry } from '../schemas/adapter-descriptor';
+
+// UNIVERSAL SQL DATABASE HANDLE
+
+/**
+ * Universal SQL database handle interface.
+ *
+ * Abstracts the underlying SQL driver (bun:sqlite, better-sqlite3, postgres, etc.)
+ * to keep storage core universal (no Node/Bun/SQL imports in core).
+ *
+ * Exposes only the surface area that storage core actually uses.
+ */
+export interface SqlDatabaseHandle {
+	exec(sql: string): void;
+	query<T, P extends any[] = unknown[]>(sql: string): SqlStatement<T, P>;
+}
+
+/**
+ * Prepared SQL statement returned by SqlDatabaseHandle.query()
+ */
+export interface SqlStatement<T, P extends any[] = unknown[]> {
+	all(...params: P): T[];
+	get(...params: P): T | undefined;
+	run(...params: P): void;
+}
+
+// PROTOCOLS & CAPABILITIES
+
+/**
+ * Storage protocols supported by adapters
+ */
+export type StorageProtocol = 'document' | 'keyvalue' | 'repository' | 'record';
+
+/**
+ * Storage adapter capabilities
+ */
+export interface StorageAdapterCapabilities {
+	/** Supported protocols */
+	protocols: StorageProtocol[];
+	/**
+	 * Coarse-grained capability flags mirroring the descriptor's
+	 * `capabilities[]`. `browse` indicates `list(driveId, path)` +
+	 * `listDrives()` are implemented.
+	 */
+	capabilities?: StorageCapability[];
+	/** Whether adapter requires pair schema (key + value) for main storage */
+	requiresPairSchema: boolean;
+	/** Whether adapter supports transactions */
+	supportsTransactions: boolean;
+	/** Whether adapter supports TTL (for caches) */
+	supportsTTL: boolean;
+	/** Whether adapter supports full-text search */
+	supportsFTS: boolean;
+	/** Whether adapter is persistent (survives restarts) */
+	persistent: boolean;
+	/** Whether adapter supports change subscriptions */
+	supportsSubscription: boolean;
+	/** Whether adapter supports hierarchical/recursive queries */
+	supportsHierarchy: boolean;
+	/** Whether adapter supports computed fields (aggregations) */
+	supportsComputedFields: boolean;
+	/** Whether adapter supports cross-table side effects */
+	supportsSideEffects: boolean;
+	/** Whether adapter supports raw SQL queries */
+	supportsRawQueries: boolean;
+}
+
+// MAIN ADAPTER INTERFACE
+
+/**
+ * Main storage adapter interface
+ *
+ * @typeParam TConfig - Adapter-specific configuration type
+ *
+ * @example
+ * ```ts
+ * // LocalDB adapter (consumer hardware)
+ * interface LocalDBConfig {
+ *   basePath: string;
+ *   dbName?: string;
+ * }
+ *
+ * class LocalDBAdapter implements StorageAdapterInterface<LocalDBConfig> {
+ *   configure(config: LocalDBConfig) { ... }
+ *   documentStore(namespace, schema) { ... }
+ *   repository(tableName, schema) { ... }
+ *   record(descriptor) { ... }
+ * }
+ * ```
+ */
+export interface StorageAdapterInterface<
+	TConfig extends Record<string, unknown> = Record<string, unknown>
+> {
+	/**
+	 * Unique adapter identifier
+	 */
+	readonly id: string;
+
+	/**
+	 * Adapter capabilities
+	 */
+	readonly capabilities: StorageAdapterCapabilities;
+
+	/**
+	 * Configure the adapter with adapter-specific options
+	 * @param config Adapter-specific configuration
+	 */
+	configure(config: TConfig): void;
+
+	/**
+	 * Check if adapter is configured and ready
+	 */
+	isConfigured(): boolean;
+
+	// Document Store (single-doc storage)
+
+	/**
+	 * Get a document store for a namespace
+	 *
+	 * @param namespace Storage namespace (e.g., 'ai.config')
+	 * @param schema Zod schema for validation
+	 * @param manifest Storage manifest descriptor (contains adapter-specific config)
+	 * @returns Document store interface
+	 * @throws If adapter doesn't support document protocol
+	 *
+	 * @example
+	 * ```ts
+	 * const store = adapter.documentStore('ai.config', aiConfigSchema, manifest);
+	 * const config = await store.load();
+	 * ```
+	 */
+	documentStore<T>(
+		namespace: string,
+		schema: z.ZodType<T>,
+		manifest?: unknown
+	): StorageDocumentStoreInterface<T>;
+
+	// Key-Value Store (pair-schema storage)
+
+	/**
+	 * Get a key-value store for a namespace
+	 *
+	 * @param namespace Storage namespace (e.g., 'cache')
+	 * @param keySchema Zod schema for keys
+	 * @param valueSchema Zod schema for values
+	 * @returns Key-value store interface
+	 * @throws If adapter doesn't support keyvalue protocol
+	 *
+	 * @example
+	 * ```ts
+	 * const kv = adapter.keyValueStore('cache', z.string(), userSchema);
+	 * await kv.set('user:123', userData);
+	 * ```
+	 */
+	keyValueStore<TKey, TValue>(
+		namespace: string,
+		keySchema: z.ZodType<TKey>,
+		valueSchema: z.ZodType<TValue>
+	): StorageKeyValueInterface<TKey, TValue>;
+
+	// Repository (structured records - legacy pattern)
+
+	/**
+	 * Get a repository for a table/collection
+	 *
+	 * @param tableName Table or collection name
+	 * @param schema Zod schema for records
+	 * @param options Repository options
+	 * @returns Repository interface
+	 * @throws If adapter doesn't support repository protocol
+	 *
+	 * @example
+	 * ```ts
+	 * const repo = adapter.repository('providers', providerSchema);
+	 * const providers = await repo.list({ limit: 10 });
+	 * ```
+	 */
+	repository<T>(
+		tableName: string,
+		schema: z.ZodType<T>,
+		options?: RepositoryOptions
+	): StorageRepositoryInterface<T>;
+
+	// Record (new descriptor-driven pattern)
+
+	/**
+	 * Get a storage record interface for CRUD operations on a single table.
+	 *
+	 * This is the new pattern for storage that uses descriptors to define
+	 * schema, relations, indexes, and advanced features.
+	 *
+	 * @param descriptor - Storage record descriptor
+	 * @returns Storage record interface with CRUD and advanced operations
+	 *
+	 * @example
+	 * ```typescript
+	 * const todos = adapter.record(todoDescriptor);
+	 * await todos.initialize();
+	 *
+	 * // Basic CRUD
+	 * await todos.create({ sessionId: '...', title: '...' });
+	 * const allTodos = await todos.list({ where: { sessionId: '...' }});
+	 *
+	 * // FTS (if adapter supports it)
+	 * const results = await todos.search('implement feature');
+	 *
+	 * // Hierarchy (if adapter supports it)
+	 * const tree = await todos.getTree({ where: { sessionId: '...' }});
+	 * ```
+	 */
+	record<T = unknown>(descriptor: StorageRecordDescriptor): StorageRecordInterface<T>;
+
+	// Browse (optional — adapters declaring `browse` capability implement these)
+
+	/**
+	 * Enumerate the top-level "drives" exposed by this adapter.
+	 *
+	 * A drive is the unit of selection before drilling into folders —
+	 * for SharePoint, a site; for OneDrive, the user's default drive; etc.
+	 *
+	 * Only adapters that declare the `browse` capability in their
+	 * descriptor are required to implement this method. Adapters that
+	 * don't browse omit it.
+	 *
+	 * @returns Promise resolving to all drives the current credential can see.
+	 */
+	listDrives?(): Promise<StorageDrive[]>;
+
+	/**
+	 * Enumerate files + directories inside a drive at the given path.
+	 *
+	 * Only adapters that declare the `browse` capability are required to
+	 * implement this method. Adapters that don't browse omit it.
+	 *
+	 * @param driveId - Drive identifier from `listDrives()`.
+	 * @param path - Path relative to the drive root. Use `''` (or omit
+	 *   when calling with two args) for the drive's top level. Segments
+	 *   joined with `/`.
+	 * @returns Promise resolving to the entries at that path.
+	 */
+	list?(driveId: string, path?: string): Promise<StorageEntry[]>;
+
+	// Database Access
+
+	/**
+	 * Ensure adapter is fully initialized and database is ready for use.
+	 * Unlike initialize(), this also creates the database connection on first access.
+	 * Called by StorageRecord before accessing the database.
+	 */
+	ensureReady(): Promise<void>;
+
+	/**
+	 * Get the underlying database connection.
+	 * Must call ensureReady() first.
+	 *
+	 * @returns The raw database connection (e.g., bun:sqlite Database)
+	 * @throws If database is not initialized
+	 */
+	getDatabaseConnection(): unknown;
+
+	// Lifecycle
+
+	/**
+	 * Initialize the adapter (create tables, connect, etc.)
+	 * Called automatically on first use if not called explicitly.
+	 */
+	initialize(): Promise<void>;
+
+	/**
+	 * Close connections and clean up
+	 */
+	close(): Promise<void>;
+
+	/**
+	 * Check adapter health
+	 */
+	healthCheck(): Promise<StorageHealthStatus>;
+}
+
+// HEALTH STATUS
+
+/**
+ * Health check result
+ */
+export interface StorageHealthStatus {
+	healthy: boolean;
+	latencyMs?: number;
+	error?: string;
+	details?: Record<string, unknown>;
+}
+
+// ADAPTER DESCRIPTOR EXTENSION
+
+/**
+ * Extended adapter descriptor for storage adapters
+ * Adds storage-specific fields to the base AdapterDescriptor
+ */
+export interface StorageAdapterDescriptorFields {
+	/** Storage protocols supported */
+	protocols: StorageProtocol[];
+	/** Whether adapter requires pair schema */
+	requiresPairSchema: boolean;
+	/** Additional capability flags */
+	supportsTransactions?: boolean;
+	supportsTTL?: boolean;
+	supportsFTS?: boolean;
+	persistent?: boolean;
+	supportsHierarchy?: boolean;
+	supportsComputedFields?: boolean;
+	supportsSideEffects?: boolean;
+	supportsRawQueries?: boolean;
+}
+
+// CONFIG TYPES FOR COMMON ADAPTERS
+
+/**
+ * Config for file-based adapters (JSON, SQLite)
+ */
+export interface FileBasedAdapterConfig {
+	/** Base path for storage files */
+	basePath: string;
+	/** Index signature for Record<string, unknown> compatibility */
+	[key: string]: unknown;
+}
+
+/**
+ * Config for LocalDB adapter (SQLite)
+ */
+export interface LocalDBAdapterConfig extends FileBasedAdapterConfig {
+	/** Database file name (default: 'vibes.db') */
+	dbName?: string;
+	/** Workspace root used for scope template resolution */
+	workspacePath?: string;
+	/** WAL mode (default: true) */
+	walMode?: boolean;
+	/** Whether to use custom tables instead of generic vibes_* tables */
+	customTables?: boolean;
+	/** Migration key for custom tables (required if customTables = true) */
+	migrationKey?: string;
+	/** Custom table name for single-table manifests */
+	tableName?: string;
+	/** Manifest ID this config is associated with */
+	manifestId?: string;
+	/** Namespace of the manifest */
+	namespace?: string;
+}
+
+/**
+ * Config for JSON adapter
+ */
+export interface JSONAdapterConfig extends FileBasedAdapterConfig {
+	/** Optional filename override for document manifests */
+	filename?: string;
+	/** Pretty print JSON (default: false in prod) */
+	prettyPrint?: boolean;
+}
+
+/**
+ * Config for Memory adapter
+ */
+export interface MemoryAdapterConfig {
+	/** Maximum items per namespace (for cache eviction) */
+	maxItems?: number;
+	/** Default TTL in milliseconds */
+	defaultTTL?: number;
+	/** Index signature for Record<string, unknown> compatibility */
+	[key: string]: unknown;
+}
+
+/**
+ * Config for Cloud Direct adapter (running ON cloud)
+ */
+export interface CloudDirectAdapterConfig {
+	/** Database connection string */
+	connectionString: string;
+	/** Database schema (for Postgres) */
+	schema?: string;
+	/** Connection pool size */
+	poolSize?: number;
+}
+
+/**
+ * Config for Cloud API adapter (consumer → cloud bridge)
+ */
+export interface CloudAPIAdapterConfig {
+	/** API endpoint URL (full origin, e.g. `https://ai.vibes.dev`). Optional
+	 * when `ownerApp` is set — the adapter then resolves the origin from
+	 * `config/environment.apps[ownerApp]` at init time. */
+	apiEndpoint?: string;
+	/** Owning app id (e.g. `'ai'`, `'tools'`, `'platform'`). When set, the
+	 * adapter looks up `config/environment.apps[ownerApp]` to determine
+	 * the base origin for requests. Lets storage manifests declare which
+	 * cloud worker hosts their data without hardcoding origins per
+	 * environment. Pairs with the runtime's `config/environment` kind so
+	 * the same descriptor works in local / staging / production. */
+	ownerApp?: string;
+	/** API authentication token */
+	apiToken?: string;
+	/** Request timeout in milliseconds */
+	timeout?: number;
+	/** Index signature for Record<string, unknown> compatibility */
+	[key: string]: unknown;
+}
+
+/**
+ * Cloud settings client interface for API-based storage.
+ * Generic methods allow type-safe storage operations.
+ */
+export interface CloudSettingsClient {
+	/** Get settings from cloud */
+	get<T>(namespace: string): Promise<T | null>;
+	/** Set settings in cloud */
+	set<T>(namespace: string, data: T): Promise<void>;
+	/** Reconcile a records collection against its canonical CRUD endpoint */
+	reconcile<T extends Record<string, unknown>>(namespace: string, data: T): Promise<void>;
+	/** Perform a raw request against a configured cloud endpoint */
+	request<T>(path: string, options?: RequestInit): Promise<T | null>;
+	/** Delete settings from cloud */
+	delete(namespace: string): Promise<void>;
+	/** Check if settings exist */
+	exists(namespace: string): Promise<boolean>;
+}
+
+/**
+ * Config for Encrypted adapter (decorator)
+ */
+export interface EncryptedAdapterConfig extends FileBasedAdapterConfig {
+	/** Encryption key (derived from user secret) */
+	encryptionKey?: string;
+	/** Key derivation parameters */
+	keyDerivation?: {
+		salt?: string;
+		iterations?: number;
+	};
+}

package/src/interfaces/document-store.ts

@@ -0,0 +1,74 @@
+/**
+ * Storage Document Store Interface
+ *
+ * Simple document store for loading/saving single documents.
+ * Schema validation is handled by the adapter.
+ */
+
+import type { z } from 'zod/v4';
+
+/**
+ * Callback for change subscriptions
+ */
+export type DocumentChangeCallback<T> = (data: T | null) => void;
+
+/**
+ * Unsubscribe function returned by subscribe()
+ */
+export type Unsubscribe = () => void;
+
+/**
+ * Document store for single-document storage
+ *
+ * @example
+ * ```ts
+ * const store = adapter.documentStore('ai.config', aiConfigSchema);
+ * const config = await store.load();
+ * await store.save({ ...config, temperature: 0.7 });
+ * ```
+ */
+export interface StorageDocumentStoreInterface<T> {
+	/**
+	 * Load the document
+	 * @returns The document or null if not found
+	 */
+	load(): Promise<T | null>;
+
+	/**
+	 * Save the document
+	 * @param data The document to save
+	 */
+	save(data: T): Promise<void>;
+
+	/**
+	 * Check if the document exists
+	 */
+	exists(): Promise<boolean>;
+
+	/**
+	 * Delete the document
+	 */
+	delete(): Promise<void>;
+
+	/**
+	 * Get the storage path/location (for debugging)
+	 */
+	getPath(): string;
+
+	/**
+	 * Subscribe to changes to this document.
+	 * Returns an unsubscribe function.
+	 * Only supported if adapter capabilities include supportsSubscription.
+	 * @param callback Function called when document changes
+	 * @returns Unsubscribe function
+	 */
+	subscribe?(callback: DocumentChangeCallback<T>): Unsubscribe;
+}
+
+/**
+ * Factory type for creating document stores
+ */
+export type DocumentStoreFactory<T> = (
+	namespace: string,
+	schema: z.ZodType<T>
+) => StorageDocumentStoreInterface<T>;

package/src/interfaces/index.ts

@@ -0,0 +1,117 @@
+/**
+ * Storage Interfaces
+ *
+ * Core interfaces for the storage module:
+ * - StorageAdapterInterface: Main adapter with document, key-value, and repository support
+ * - StorageDocumentStoreInterface: Single-document storage
+ * - StorageKeyValueInterface: Key-value storage (pair schema)
+ * - StorageRepositoryInterface: Structured record storage with queries
+ */
+
+// Main adapter interface
+export {
+	type StorageAdapterInterface,
+	type StorageAdapterCapabilities,
+	type StorageAdapterDescriptorFields,
+	type StorageProtocol,
+	type StorageHealthStatus,
+	type CloudSettingsClient,
+	// Config types
+	type FileBasedAdapterConfig,
+	type LocalDBAdapterConfig,
+	type JSONAdapterConfig,
+	type MemoryAdapterConfig,
+	type CloudDirectAdapterConfig,
+	type CloudAPIAdapterConfig,
+	type EncryptedAdapterConfig
+} from './adapter';
+
+// Document store interface
+export { type StorageDocumentStoreInterface, type DocumentStoreFactory } from './document-store';
+
+// Key-value interface
+export {
+	type StorageKeyValueInterface,
+	type KeyValueSetOptions,
+	type KeyValueStoreFactory
+} from './key-value';
+
+// Repository interface
+export {
+	type StorageRepositoryInterface,
+	type RepositoryCreateInput,
+	type RepositoryUpdateInput,
+	type RepositoryQuery,
+	type QueryCondition,
+	type RepositoryListOptions,
+	type RepositoryFindOptions,
+	type RepositoryOrderBy,
+	type RepositoryPage,
+	type RepositoryMeta,
+	type RepositoryFactory,
+	type RepositoryOptions
+} from './repository';
+
+// Storage record interface (single table CRUD)
+export {
+	// Query types
+	type WhereFilter,
+	type OrderBy,
+	type IncludeRelations,
+	type PaginationOptions,
+	type QueryOptions,
+	type QueryResult,
+	// Create types
+	type CreateInput,
+	type CreateManyOptions,
+	// Update types
+	type UpdateInput,
+	type UpdateOptions,
+	type UpdateResult,
+	// Delete types
+	type DeleteOptions,
+	type DeleteResult,
+	// Relation types
+	type LoadedRelation,
+	type RecordWithRelations,
+	// Transaction types
+	type TransactionContext,
+	type TransactionFn,
+	// Aggregation types
+	type AggregationFunction,
+	type AggregationOptions,
+	type AggregationResult,
+	// Stream types
+	type StreamOptions,
+	// Main interface
+	type StorageRecordInterface
+} from './record';
+
+// Query-builder database interface (Drizzle-ORM-compatible)
+export { type QueryBuilderDatabase } from './query-builder';
+
+// Storage schema interface (multi-table schemas)
+export {
+	// Table interface
+	type StorageTableInterface,
+	// Main interface
+	type StorageSchemaInterface,
+	// Migration types
+	type MigrationStatus,
+	type MigrationOptions,
+	type MigrationResult,
+	// Backup types
+	type BackupOptions,
+	type BackupResult,
+	type RestoreOptions,
+	type RestoreResult,
+	// Sync types
+	type SyncStatus,
+	type SyncOptions,
+	type SyncResult,
+	// Query types
+	type CrossTableQueryOptions,
+	// Metadata types
+	type SchemaStatistics,
+	type SchemaHealthStatus
+} from './schema';