@vibesdotdev/storage 0.0.1

package/src/docs/manifests.docs.descriptor.ts

@@ -0,0 +1,318 @@
+import type { DocsTopicDescriptor } from '@vibesdotdev/docs';
+
+const descriptor: DocsTopicDescriptor = {
+	kind: 'docs/topic',
+	id: 'storage.manifests',
+	title: 'Storage Manifests',
+	summary: 'Manifest declarations, allowed adapters, and namespace organization',
+	body: {
+		type: 'markdown',
+		sourceType: 'raw',
+		source: `---
+title: Storage Manifests
+summary: Manifest declarations, allowed adapters, and namespace organization
+tags: [storage, manifests, declarations, adapters, namespaces]
+parent: storage
+order: 4
+surfaces: [cli, web, in-app]
+hardware: [consumer, cloud]
+---
+
+# Storage Manifests
+
+Manifests declare the structure and storage requirements for a data type. The \`storage/manifest\` runtime kind defines what data to store, which adapters are allowed, and how the data is organized.
+
+## Manifest Structure
+
+\`\`\`ts
+interface StorageManifestDescriptor {
+  kind: 'storage/manifest';
+  id: string;                    // unique identifier
+  namespace: string;             // organizational namespace
+  schema: ZodSchema;             // data validation schema
+  allowedAdapters?: string[];    // allowed adapter IDs
+  adapterConfig?: {
+    [adapterId: string]: {
+      [key: string]: unknown;
+    };
+  };
+  context?: {
+    hardware?: ('consumer' | 'cloud')[];
+    environment?: string[];
+  };
+  enabled?: boolean;
+}
+\`\`\`
+
+## Defining a Manifest
+
+### Basic Manifest
+
+\`\`\`ts
+import { z } from 'zod';
+import type { StorageManifestDescriptor } from '@vibesdotdev/storage';
+
+const settingsManifest: StorageManifestDescriptor = {
+  kind: 'storage/manifest',
+  id: 'app/settings',
+  namespace: 'app',
+  schema: z.object({
+    theme: z.enum(['light', 'dark', 'system']),
+    language: z.string().default('en'),
+    notifications: z.boolean().default(true),
+    autoSave: z.boolean().default(true)
+  })
+};
+\`\`\`
+
+### Manifest with Adapter Constraints
+
+\`\`\`ts
+const userPreferencesManifest: StorageManifestDescriptor = {
+  kind: 'storage/manifest',
+  id: 'user/preferences',
+  namespace: 'user',
+  schema: z.object({
+    // ... schema fields
+  }),
+  allowedAdapters: [
+    'storage.adapter.libsql',
+    'storage.adapter.d1',
+    'storage.adapter.drizzle'
+  ],
+  adapterConfig: {
+    'storage.cloud-api': {
+      endpoint: 'https://storage.vibes.dev/user/preferences'
+    }
+  }
+};
+\`\`\`
+
+### Manifest with Context Rules
+
+\`\`\`ts
+const productionConfigManifest: StorageManifestDescriptor = {
+  kind: 'storage/manifest',
+  id: 'app/production-config',
+  namespace: 'app',
+  schema: z.object({
+    // ... schema fields
+  }),
+  context: {
+    hardware: ['cloud'],
+    environment: ['production']
+  }
+};
+\`\`\`
+
+## Using StorageManifest Class
+
+The \`StorageManifest\` class provides document operations:
+
+\`\`\`ts
+import { StorageManifest } from '@vibesdotdev/storage';
+import { getVibesRuntime } from '@vibesdotdev/runtime';
+
+const runtime = getVibesRuntime();
+
+// Create manifest instance
+const settings = new StorageManifest('app/settings');
+
+// Load data
+const data = await settings.load();
+
+// Save data
+await settings.save({
+  theme: 'dark',
+  language: 'en',
+  notifications: true
+});
+
+// Check existence
+const exists = await settings.exists();
+
+// Delete data
+await settings.delete();
+\`\`\`
+
+## Manifest Namespaces
+
+Namespaces organize manifests hierarchically:
+
+\`\`\`
+app/settings
+app/preferences
+app/theme
+user/profile
+user/preferences
+system/config
+\`\`\`
+
+**Namespace conventions:**
+- \`app/*\` — Application-level configuration
+- \`user/*\` — User-specific data
+- \`system/*\` — System-wide configuration
+- \`workspace/*\` — Workspace-shared data
+
+## Adapter Configuration
+
+Manifests can configure adapter-specific behavior:
+
+### Cloud-API Endpoint
+
+\`\`\`ts
+{
+  adapterConfig: {
+    'storage.cloud-api': {
+      endpoint: 'https://storage.vibes.dev/app/settings',
+      auth: 'bearer-token'
+    }
+  }
+}
+\`\`\`
+
+### Drizzle Table Name
+
+\`\`\`ts
+{
+  adapterConfig: {
+    'storage.adapter.drizzle': {
+      tableName: 'app_settings',
+      schemaName: 'public'
+    }
+  }
+}
+\`\`\`
+
+### LibSQL Database Path
+
+\`\`\`ts
+{
+  adapterConfig: {
+    'storage.adapter.libsql': {
+      dbPath: './data/app.db',
+      authToken: 'optional-token'
+    }
+  }
+}
+\`\`\`
+
+## Manifest Inheritance
+
+Manifests can extend other manifests:
+
+\`\`\`ts
+const baseManifest: StorageManifestDescriptor = {
+  kind: 'storage/manifest',
+  id: 'app/base-settings',
+  namespace: 'app',
+  schema: z.object({
+    theme: z.enum(['light', 'dark']),
+    language: z.string()
+  })
+};
+
+const extendedManifest: StorageManifestDescriptor = {
+  ...baseManifest,
+  id: 'app/extended-settings',
+  schema: baseManifest.schema.extend({
+    notifications: z.boolean(),
+    autoSave: z.boolean()
+  })
+};
+\`\`\`
+
+## Manifest Validation
+
+Manifests validate data on load and save:
+
+\`\`\`ts
+try {
+  const settings = new StorageManifest('app/settings');
+  await settings.save({ theme: 'invalid' });  // fails validation
+} catch (error) {
+  console.error(error);  // ZodError with details
+}
+\`\`\`
+
+## Manifest Migration
+
+Update schemas while maintaining backward compatibility:
+
+\`\`\`ts
+const settingsManifestV2: StorageManifestDescriptor = {
+  kind: 'storage/manifest',
+  id: 'app/settings',
+  namespace: 'app',
+  schema: z.object({
+    theme: z.enum(['light', 'dark', 'system']),
+    language: z.string().default('en'),
+    // New field with default for migration
+    notifications: z.boolean().default(true)
+  }),
+  // Migration transform
+  transform: {
+    fromRow: (row) => ({
+      ...row,
+      notifications: row.notifications ?? true
+    })
+  }
+};
+\`\`\`
+
+## Listing Manifests
+
+List all registered manifests:
+
+\`\`\`bash
+vibes storage list --kind manifest
+\`\`\`
+
+**Output:**
+\`\`\`
+ID                     Namespace    Adapters
+────────────────────────────────────────────────
+app/settings           app          libsql, cloud-api
+user/preferences       user         drizzle, cloud-api
+system/config          system       d1
+\`\`\`
+
+## Manifest Discovery
+
+Query manifests by namespace:
+
+\`\`\`ts
+const appManifests = runtime.query('storage/manifest')
+  .filter(d => d.namespace === 'app')
+  .descriptors();
+
+const cloudManifests = runtime.query('storage/manifest')
+  .filter(d => d.context?.hardware?.includes('cloud'))
+  .descriptors();
+\`\`\`
+
+## Best Practices
+
+1. **Use descriptive IDs** — \`app/settings\` not \`settings\`
+2. **Namespace consistently** — Group related manifests
+3. **Declare adapter constraints** — Be explicit about allowed adapters
+4. **Version schemas** — Use transforms for migrations
+5. **Test with multiple adapters** — Ensure adapter compatibility
+
+:::card{title="See also"}
+- [\`storage.adapters\`](storage.adapters) — Adapter implementations
+- [\`storage.records\`](storage.records) — Record CRUD operations
+- [\`storage.sync\`](storage.sync) — Cross-app synchronization
+- [\`config.manifests\`](config.manifests) — Configuration manifests
+:::
+`
+	},
+	parent: 'storage',
+	order: 4,
+	tags: ['storage', 'manifests', 'declarations', 'adapters', 'namespaces'],
+	surfaces: ['cli', 'web', 'in-app'],
+	hardware: ['consumer', 'cloud'],
+	enabled: true
+};
+
+export default descriptor;

package/src/docs/records.docs.descriptor.ts

@@ -0,0 +1,271 @@
+import type { DocsTopicDescriptor } from '@vibesdotdev/docs';
+
+const descriptor: DocsTopicDescriptor = {
+	kind: 'docs/topic',
+	id: 'storage.records',
+	title: 'Storage Records',
+	summary: 'Record CRUD operations, typing, validation, and transforms',
+	body: {
+		type: 'markdown',
+		sourceType: 'raw',
+		source: `---
+title: Storage Records
+summary: Record CRUD operations, typing, validation, and transforms
+tags: [storage, records, crud, typing, validation]
+parent: storage
+order: 2
+surfaces: [cli, web, in-app]
+hardware: [consumer, cloud]
+---
+
+# Storage Records
+
+Records provide type-safe CRUD operations for structured data. The \`storage/record\` runtime kind defines the interface for single-table operations with automatic validation and timestamps.
+
+## Record Interface
+
+\`\`\`ts
+interface StorageRecordInterface<T extends Record<string, unknown>> {
+  // Create
+  insert(data: Omit<T, 'id' | 'createdAt' | 'updatedAt'>): Promise<T>;
+  
+  // Read
+  find(id: string): Promise<T | null>;
+  findAll(query?: QueryFilter<T>): Promise<T[]>;
+  
+  // Update
+  update(id: string, data: Partial<T>): Promise<T>;
+  
+  // Delete
+  delete(id: string): Promise<void>;
+  
+  // Lifecycle
+  dispose(): Promise<void>;
+}
+\`\`\`
+
+## Defining Record Types
+
+Records are defined with Zod schemas:
+
+\`\`\`ts
+import { z } from 'zod';
+import type { StorageRecordDescriptor } from '@vibesdotdev/storage';
+
+const userRecord: StorageRecordDescriptor = {
+  kind: 'storage/record',
+  id: 'user',
+  namespace: 'app',
+  schema: z.object({
+    id: z.string().uuid(),
+    email: z.string().email(),
+    name: z.string().min(1),
+    role: z.enum(['admin', 'user', 'guest']),
+    createdAt: z.coerce.date(),
+    updatedAt: z.coerce.date()
+  })
+};
+\`\`\`
+
+## Using Records
+
+### Creating Records
+
+\`\`\`ts
+import { StorageRecord } from '@vibesdotdev/storage';
+import { getVibesRuntime } from '@vibesdotdev/runtime';
+
+const runtime = getVibesRuntime();
+const userStore = new StorageRecord(userRecord, { runtime });
+
+const user = await userStore.insert({
+  email: 'alice@example.com',
+  name: 'Alice',
+  role: 'user'
+});
+
+console.log(user);
+// { id: 'uuid...', email: 'alice@example.com', name: 'Alice', role: 'user', ... }
+\`\`\`
+
+### Querying Records
+
+\`\`\`ts
+// Find by ID
+const user = await userStore.find('user-id');
+
+// Find all with filter
+const users = await userStore.findAll({
+  where: { role: 'admin' },
+  orderBy: { field: 'createdAt', direction: 'desc' },
+  limit: 10
+});
+
+// Find first match
+const admin = await userStore.findAll({
+  where: { role: 'admin' },
+  limit: 1
+}).then(results => results[0]);
+\`\`\`
+
+### Updating Records
+
+\`\`\`ts
+const updated = await userStore.update('user-id', {
+  name: 'Alice Updated'
+});
+
+// updatedAt is automatically managed
+console.log(updated.updatedAt); // new Date()
+\`\`\`
+
+### Deleting Records
+
+\`\`\`ts
+await userStore.delete('user-id');
+
+// Verify deletion
+const exists = await userStore.find('user-id');
+console.log(exists); // null
+\`\`\`
+
+## Automatic Timestamps
+
+Records automatically manage \`createdAt\` and \`updatedAt\` fields:
+
+- \`createdAt\` — Set on insert, immutable
+- \`updatedAt\` — Updated on every update operation
+
+These fields are added automatically if not in your schema. To disable:
+
+\`\`\`ts
+const record: StorageRecordDescriptor = {
+  ...
+  schema: z.object({
+    // your fields
+  }),
+  timestamps: false  // disable automatic timestamps
+};
+\`\`\`
+
+## Validation
+
+Records validate data against the schema on every operation:
+
+\`\`\`ts
+try {
+  await userStore.insert({
+    email: 'not-an-email',  // fails validation
+    name: 'Bob'
+  });
+} catch (error) {
+  console.error(error);  // ZodError with validation details
+}
+\`\`\`
+
+## Record Transforms
+
+Transforms convert between storage and application formats:
+
+\`\`\`ts
+import { defineStorageTransform } from '@vibesdotdev/storage';
+
+const userTransform = defineStorageTransform({
+  id: 'user.transform',
+  fromRow: (row) => ({
+    ...row,
+    displayName: row.name.toUpperCase()
+  }),
+  toRow: (data) => ({
+    ...data,
+    name: data.displayName.toLowerCase()
+  })
+});
+\`\`\`
+
+Apply transforms when creating the record store:
+
+\`\`\`ts
+const userStore = new StorageRecord(userRecord, {
+  runtime,
+  transform: userTransform
+});
+\`\`\`
+
+## Relations
+
+Records support relations to other records:
+
+\`\`\`ts
+const postRecord: StorageRecordDescriptor = {
+  kind: 'storage/record',
+  id: 'post',
+  namespace: 'app',
+  schema: z.object({
+    id: z.string(),
+    title: z.string(),
+    authorId: z.string().uuid(),
+    content: z.string()
+  }),
+  relations: {
+    author: {
+      type: 'one',
+      target: 'user',
+      foreignKey: 'authorId'
+    }
+  }
+};
+\`\`\`
+
+## Record Events
+
+Records emit lifecycle events:
+
+\`\`\`ts
+import { storageRecordEvents } from '@vibesdotdev/storage';
+
+runtime.registerDescriptor('event', storageRecordEvents.onInsert);
+runtime.registerDescriptor('event', storageRecordEvents.onUpdate);
+runtime.registerDescriptor('event', storageRecordEvents.onDelete);
+
+// Subscribe to events
+runtime.on('storage/record:insert', (event) => {
+  console.log('Record inserted:', event.recordId);
+});
+\`\`\`
+
+## Storage Policy
+
+Records respect storage policies for access control:
+
+\`\`\`ts
+import { StoragePolicyContext } from '@vibesdotdev/storage';
+
+const policyContext: StoragePolicyContext = {
+  userId: 'current-user',
+  roles: ['user'],
+  capabilities: ['storage:read', 'storage:write']
+};
+
+const userStore = new StorageRecord(userRecord, {
+  runtime,
+  context: { 'storage/policy': policyContext }
+});
+\`\`\`
+
+:::card{title="See also"}
+- [\`storage.adapters\`](storage.adapters) — Adapter implementations
+- [\`storage.manifests\`](storage.manifests) — Manifest declarations
+- [\`storage.sync\`](storage.sync) — Cross-app synchronization
+:::
+`
+	},
+	parent: 'storage',
+	order: 2,
+	tags: ['storage', 'records', 'crud', 'typing', 'validation'],
+	surfaces: ['cli', 'web', 'in-app'],
+	hardware: ['consumer', 'cloud'],
+	enabled: true
+};
+
+export default descriptor;