@vibesdotdev/storage 0.0.2 → 1.0.0-rc.3

package/dist/docs/storage.browse.docs.descriptor.js

@@ -0,0 +1,74 @@
+const descriptor = {
+    kind: 'docs/topic',
+    id: 'storage.browse',
+    title: 'Storage Browse',
+    summary: 'Browsing browse-capable storage adapters (SharePoint, …) — listBrowsableStorageAdapters, browseStorageDrives/Entries, the platform client surface, and the StorageBrowser component',
+    body: {
+        type: 'markdown',
+        sourceType: 'raw',
+        source: `---
+title: Storage Browse
+summary: Enumerate drives + folders of browse-capable storage adapters through the runtime
+tags: [storage, browse, adapters, sharepoint, picker]
+parent: storage
+order: 6
+surfaces: [web, in-app]
+hardware: [consumer, cloud]
+---
+
+# Storage Browse
+
+Some \`storage/adapter\`s are *browsable*: they declare the \`'browse'\` capability and implement \`listDrives()\` + \`list(driveId, path)\`. Browse is distinct from record CRUD (see [\`storage.records\`](storage.records)) — it is a live, read-through view of an external hierarchy (e.g. a customer's SharePoint sites and folders), not owned rows.
+
+## Discovering browsable adapters
+
+\`listBrowsableStorageAdapters(runtime)\` (from \`@vibesdotdev/storage/client\`) returns the descriptors of every registered adapter that declares \`'browse'\` — descriptor-only, no implementation load. Use it to build a picker of available sources.
+
+## Browsing an adapter
+
+\`@vibesdotdev/storage/client\` resolves the adapter implementation and invokes it:
+
+\`\`\`ts
+import { browseStorageDrives, browseStorageEntries } from '@vibesdotdev/storage/client';
+
+// \`runtime\` is the one the request or command was handed (\`ctx.runtime\`).
+const drives = await browseStorageDrives(runtime, 'sharepoint');           // → StorageDrive[]
+const entries = await browseStorageEntries(runtime, 'sharepoint', driveId, path); // → StorageEntry[]
+\`\`\`
+
+These throw \`StorageAdapterNotFoundError\` (unknown id) or \`StorageAdapterNotBrowsableError\` (adapter lacks the capability); an adapter whose load fails rejects with its own error. The handed runtime resolves the impl for its scope and request context, so credentialed adapters (SharePoint's delegated token, …) acquire auth from the surrounding request context — call them inside the caller's user/org context on the server.
+
+## Consuming from an app (the runtime-resolved path)
+
+Apps do not import adapters or hit bespoke endpoints. The browser resolves browse through the canonical platform \`runtime/client\`:
+
+\`\`\`ts
+const platform = await getVibesPlatformClient();
+const drives = await platform.storage.browse.listDrives('sharepoint');
+const entries = await platform.storage.browse.list('sharepoint', driveId, path);
+\`\`\`
+
+This calls platform-web's \`GET /api/storage/adapters/[id]/{drives,entries}\` (session-authed, wrapped in the caller's request context). A missing credential maps to HTTP **412** so the UI can show a connect CTA.
+
+## UI surface
+
+\`@vibesdotdev/storage/svelte\` ships the reusable browser:
+
+- \`StorageBrowseStore\` (\`./svelte/stores\`) — reactive drives/entries/path + \`connected\` state.
+- \`StorageBrowser\` / \`StorageBrowserPage\` (\`./svelte/StorageBrowser.svelte\`, \`./svelte/StorageBrowserPage.svelte\`) — drive picker → breadcrumb navigation → entry list, with pluggable \`rowActions\` / \`headerActions\` / \`decorate(entry, ctx)\` so consumers add affordances (e.g. "Create job from folder", "Job linked") without domain logic in the surface.
+
+:::card{title="See also"}
+- [\`storage.adapters\`](storage.adapters) — the adapter interface + \`browse\` capability
+- [\`storage.records\`](storage.records) — owned-record CRUD (the other axis)
+:::
+`
+    },
+    parent: 'storage',
+    order: 6,
+    tags: ['storage', 'browse', 'adapters', 'sharepoint', 'picker'],
+    surfaces: ['web', 'in-app'],
+    hardware: ['consumer', 'cloud'],
+    enabled: true
+};
+export default descriptor;
+//# sourceMappingURL=storage.browse.docs.descriptor.js.map

package/dist/docs/storage.browse.docs.descriptor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"storage.browse.docs.descriptor.js","sourceRoot":"","sources":["../../src/docs/storage.browse.docs.descriptor.ts"],"names":[],"mappings":"AAEA,MAAM,UAAU,GAAwB;IACvC,IAAI,EAAE,YAAY;IAClB,EAAE,EAAE,gBAAgB;IACpB,KAAK,EAAE,gBAAgB;IACvB,OAAO,EACN,qLAAqL;IACtL,IAAI,EAAE;QACL,IAAI,EAAE,UAAU;QAChB,UAAU,EAAE,KAAK;QACjB,MAAM,EAAE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAuDT;KACC;IACD,MAAM,EAAE,SAAS;IACjB,KAAK,EAAE,CAAC;IACR,IAAI,EAAE,CAAC,SAAS,EAAE,QAAQ,EAAE,UAAU,EAAE,YAAY,EAAE,QAAQ,CAAC;IAC/D,QAAQ,EAAE,CAAC,KAAK,EAAE,QAAQ,CAAC;IAC3B,QAAQ,EAAE,CAAC,UAAU,EAAE,OAAO,CAAC;IAC/B,OAAO,EAAE,IAAI;CACb,CAAC;AAEF,eAAe,UAAU,CAAC"}

package/dist/docs/storage.docs.descriptor.d.ts

@@ -0,0 +1,4 @@
+import type { DocsTopicDescriptor } from '@vibesdotdev/docs-contracts';
+declare const descriptor: DocsTopicDescriptor;
+export default descriptor;
+//# sourceMappingURL=storage.docs.descriptor.d.ts.map

package/dist/docs/storage.docs.descriptor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"storage.docs.descriptor.d.ts","sourceRoot":"","sources":["../../src/docs/storage.docs.descriptor.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,6BAA6B,CAAC;AAoCvE,QAAA,MAAM,UAAU,EAAE,mBAejB,CAAC;AAEF,eAAe,UAAU,CAAC"}

package/dist/docs/storage.docs.descriptor.js

@@ -0,0 +1,51 @@
+const storageMarkdown = `---
+title: Storage
+summary: Records, adapters, transforms, manifests, sync, and browse.
+parent: 
+order: 5
+---
+
+# Storage
+
+Records, adapters, transforms, manifests, sync, and browse. Storage is descriptor-driven — a \`storageDescriptorId\` resolves an adapter (where rows live) and a transform (how rows map to API shape).
+
+## When to use
+
+Reach for storage when a feature needs to persist or read structured rows (records, drafts, collections) without hard-coding a backend — declare a manifest and let the runtime resolve the right adapter (D1, KV, R2, IndexedDB) per surface and hardware.
+
+## How it resolves
+
+Adapters are runtime-resolved capabilities of kind \`storage/adapter\`. App code never news-up a backend; it queries the runtime and the matching descriptor wins:
+
+\`\`\`ts
+// \`runtime\` is the VibesRuntime you were handed: \`context.runtime\` in a tool, command or job, or the plugin's \`RuntimeRef\`.
+const adapter = await runtime.query('storage/adapter').first();
+\`\`\`
+
+:::card{title="In this section"}
+- [\`storage.adapters\`](storage.adapters) — Storage Adapters
+- [\`storage.records\`](storage.records) — Storage Records
+- [\`storage.sync\`](storage.sync) — Storage Sync
+- [\`storage.manifests\`](storage.manifests) — Storage Manifests
+- [\`storage.transform\`](storage.transform) — Storage Transforms
+- [\`storage.browse\`](storage.browse) — Storage Browse
+:::
+`;
+const descriptor = {
+    kind: 'docs/topic',
+    id: 'storage',
+    title: 'Storage',
+    summary: "Records, adapters, transforms, manifests, sync, and browse.",
+    body: {
+        type: 'markdown',
+        sourceType: 'raw',
+        source: storageMarkdown
+    },
+    order: 5,
+    tags: ['storage', 'overview'],
+    surfaces: ['web', 'in-app'],
+    hardware: ['consumer', 'cloud'],
+    enabled: true
+};
+export default descriptor;
+//# sourceMappingURL=storage.docs.descriptor.js.map

package/dist/docs/storage.docs.descriptor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"storage.docs.descriptor.js","sourceRoot":"","sources":["../../src/docs/storage.docs.descriptor.ts"],"names":[],"mappings":"AAEA,MAAM,eAAe,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAgCvB,CAAC;AAEF,MAAM,UAAU,GAAwB;IACvC,IAAI,EAAE,YAAY;IAClB,EAAE,EAAE,SAAS;IACb,KAAK,EAAE,SAAS;IAChB,OAAO,EAAE,6DAA6D;IACtE,IAAI,EAAE;QACL,IAAI,EAAE,UAAU;QAChB,UAAU,EAAE,KAAK;QACjB,MAAM,EAAE,eAAe;KACvB;IACD,KAAK,EAAE,CAAC;IACR,IAAI,EAAE,CAAC,SAAS,EAAE,UAAU,CAAC;IAC7B,QAAQ,EAAE,CAAC,KAAK,EAAE,QAAQ,CAAC;IAC3B,QAAQ,EAAE,CAAC,UAAU,EAAE,OAAO,CAAC;IAC/B,OAAO,EAAE,IAAI;CACb,CAAC;AAEF,eAAe,UAAU,CAAC"}

package/dist/docs/storage.manifests.docs.descriptor.d.ts

@@ -0,0 +1,4 @@
+import type { DocsTopicDescriptor } from '@vibesdotdev/docs-contracts';
+declare const descriptor: DocsTopicDescriptor;
+export default descriptor;
+//# sourceMappingURL=storage.manifests.docs.descriptor.d.ts.map

package/dist/docs/storage.manifests.docs.descriptor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"storage.manifests.docs.descriptor.d.ts","sourceRoot":"","sources":["../../src/docs/storage.manifests.docs.descriptor.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,6BAA6B,CAAC;AAEvE,QAAA,MAAM,UAAU,EAAE,mBA4VjB,CAAC;AAEF,eAAe,UAAU,CAAC"}

package/dist/docs/{manifests.docs.descriptor.js → storage.manifests.docs.descriptor.js}

@@ -28,7 +28,10 @@ interface StorageManifestDescriptor {
   id: string;                    // unique identifier
   namespace: string;             // organizational namespace
   schema: ZodSchema;             // data validation schema
-  allowedAdapters?: string[];    // allowed adapter IDs
+  dataType: 'raw' | 'records' | 'objects';
+  idField?: string;              // required for records
+  allowedAdapters: string[];     // allowed adapter IDs
+  defaultAdapter?: string;
   adapterConfig?: {
     [adapterId: string]: {
       [key: string]: unknown;
@@ -47,7 +50,7 @@ interface StorageManifestDescriptor {
 ### Basic Manifest
 
 \`\`\`ts
-import { z } from 'zod';
+import * as z from 'zod/v4';
 import type { StorageManifestDescriptor } from '@vibesdotdev/storage';
 
 const settingsManifest: StorageManifestDescriptor = {
@@ -59,7 +62,10 @@ const settingsManifest: StorageManifestDescriptor = {
     language: z.string().default('en'),
     notifications: z.boolean().default(true),
     autoSave: z.boolean().default(true)
-  })
+  }),
+  dataType: 'objects',
+  allowedAdapters: ['storage.localdb'],
+  defaultAdapter: 'storage.localdb'
 };
 \`\`\`
 
@@ -73,14 +79,14 @@ const userPreferencesManifest: StorageManifestDescriptor = {
   schema: z.object({
     // ... schema fields
   }),
-  allowedAdapters: [
-    'storage.adapter.libsql',
-    'storage.adapter.d1',
-    'storage.adapter.drizzle'
-  ],
+  dataType: 'records',
+  idField: 'id',
+  allowedAdapters: ['storage.localdb', 'storage.cloud-api'],
+  defaultAdapter: 'storage.localdb',
   adapterConfig: {
     'storage.cloud-api': {
-      endpoint: 'https://storage.vibes.dev/user/preferences'
+      ownerApp: 'platform',
+      endpoint: '/api/user/preferences'
     }
   }
 };
@@ -96,6 +102,15 @@ const productionConfigManifest: StorageManifestDescriptor = {
   schema: z.object({
     // ... schema fields
   }),
+  dataType: 'objects',
+  allowedAdapters: ['storage.cloud-api'],
+  defaultAdapter: 'storage.cloud-api',
+  adapterConfig: {
+    'storage.cloud-api': {
+      ownerApp: 'platform',
+      endpoint: '/api/production-config'
+    }
+  },
   context: {
     hardware: ['cloud'],
     environment: ['production']
@@ -109,12 +124,10 @@ 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');
+// \`runtime\` is the runtime your plugin, command or job was handed; a manifest
+// resolves its adapter and paths on it, never on an ambient default.
+const settings = new StorageManifest('app/settings', { runtime });
 
 // Load data
 const data = await settings.load();
@@ -126,13 +139,36 @@ await settings.save({
   notifications: true
 });
 
+// Update data. Adapters that implement document-store update serialize
+// the read-transform-write operation; other adapters fall back to load+save.
+await settings.update((current) => ({
+  ...(current ?? {}),
+  autoSave: true
+}));
+
 // Check existence
 const exists = await settings.exists();
 
 // Delete data
 await settings.delete();
+
+// Isolate one principal/document without choosing an adapter in feature code.
+// The resolved manifest must use namespace addressing: customTables=false and
+// absent/empty config for every allowed adapter (for example storage.idb: {}).
+const drewSettings = settings.partition('local:drew');
+await drewSettings.save({
+  theme: 'dark',
+  language: 'en',
+  notifications: true
+});
 \`\`\`
 
+Partitioning intentionally rejects non-empty adapter configuration. A JSON
+\`filename\`, cloud-api \`endpoint\`, custom table, or any other adapter-specific
+locator may route several derived namespaces to the same physical document. Use
+a namespace-addressed manifest, or make partitioning part of the owning adapter
+or endpoint's explicit data model instead.
+
 ## Manifest Namespaces
 
 Namespaces organize manifests hierarchically:
@@ -162,8 +198,8 @@ Manifests can configure adapter-specific behavior:
 {
   adapterConfig: {
     'storage.cloud-api': {
-      endpoint: 'https://storage.vibes.dev/app/settings',
-      auth: 'bearer-token'
+      ownerApp: 'platform',
+      endpoint: '/api/settings'
     }
   }
 }
@@ -174,7 +210,7 @@ Manifests can configure adapter-specific behavior:
 \`\`\`ts
 {
   adapterConfig: {
-    'storage.adapter.drizzle': {
+    'storage.drizzle': {
       tableName: 'app_settings',
       schemaName: 'public'
     }
@@ -182,14 +218,13 @@ Manifests can configure adapter-specific behavior:
 }
 \`\`\`
 
-### LibSQL Database Path
+### LocalDB Database Name
 
 \`\`\`ts
 {
   adapterConfig: {
-    'storage.adapter.libsql': {
-      dbPath: './data/app.db',
-      authToken: 'optional-token'
+    'storage.localdb': {
+      dbName: 'app-settings.db'
     }
   }
 }
@@ -207,7 +242,10 @@ const baseManifest: StorageManifestDescriptor = {
   schema: z.object({
     theme: z.enum(['light', 'dark']),
     language: z.string()
-  })
+  }),
+  dataType: 'objects',
+  allowedAdapters: ['storage.localdb'],
+  defaultAdapter: 'storage.localdb'
 };
 
 const extendedManifest: StorageManifestDescriptor = {
@@ -226,7 +264,7 @@ Manifests validate data on load and save:
 
 \`\`\`ts
 try {
-  const settings = new StorageManifest('app/settings');
+  const settings = new StorageManifest('app/settings', { runtime });
   await settings.save({ theme: 'invalid' });  // fails validation
 } catch (error) {
   console.error(error);  // ZodError with details
@@ -248,13 +286,10 @@ const settingsManifestV2: StorageManifestDescriptor = {
     // New field with default for migration
     notifications: z.boolean().default(true)
   }),
-  // Migration transform
-  transform: {
-    fromRow: (row) => ({
-      ...row,
-      notifications: row.notifications ?? true
-    })
-  }
+  dataType: 'objects',
+  allowedAdapters: ['storage.localdb'],
+  defaultAdapter: 'storage.localdb',
+  version: 2
 };
 \`\`\`
 
@@ -270,9 +305,9 @@ vibes storage list --kind manifest
 \`\`\`
 ID                     Namespace    Adapters
 ────────────────────────────────────────────────
-app/settings           app          libsql, cloud-api
-user/preferences       user         drizzle, cloud-api
-system/config          system       d1
+app/settings           app          localdb, cloud-api
+user/preferences       user         localdb, cloud-api
+system/config          system       cloud-api
 \`\`\`
 
 ## Manifest Discovery
@@ -313,4 +348,4 @@ const cloudManifests = runtime.query('storage/manifest')
     enabled: true
 };
 export default descriptor;
-//# sourceMappingURL=manifests.docs.descriptor.js.map
+//# sourceMappingURL=storage.manifests.docs.descriptor.js.map

package/dist/docs/storage.manifests.docs.descriptor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"storage.manifests.docs.descriptor.js","sourceRoot":"","sources":["../../src/docs/storage.manifests.docs.descriptor.ts"],"names":[],"mappings":"AAEA,MAAM,UAAU,GAAwB;IACvC,IAAI,EAAE,YAAY;IAClB,EAAE,EAAE,mBAAmB;IACvB,KAAK,EAAE,mBAAmB;IAC1B,OAAO,EAAE,qEAAqE;IAC9E,IAAI,EAAE;QACL,IAAI,EAAE,UAAU;QAChB,UAAU,EAAE,KAAK;QACjB,MAAM,EAAE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA4UT;KACC;IACD,MAAM,EAAE,SAAS;IACjB,KAAK,EAAE,CAAC;IACR,IAAI,EAAE,CAAC,SAAS,EAAE,WAAW,EAAE,cAAc,EAAE,UAAU,EAAE,YAAY,CAAC;IACxE,QAAQ,EAAE,CAAC,KAAK,EAAE,KAAK,EAAE,QAAQ,CAAC;IAClC,QAAQ,EAAE,CAAC,UAAU,EAAE,OAAO,CAAC;IAC/B,OAAO,EAAE,IAAI;CACb,CAAC;AAEF,eAAe,UAAU,CAAC"}

package/dist/docs/sync.docs.descriptor.d.ts

@@ -1,4 +1,4 @@
-import type { DocsTopicDescriptor } from '@vibesdotdev/docs';
+import type { DocsTopicDescriptor } from '@vibesdotdev/docs-contracts';
 declare const descriptor: DocsTopicDescriptor;
 export default descriptor;
 //# sourceMappingURL=sync.docs.descriptor.d.ts.map

package/dist/docs/sync.docs.descriptor.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"sync.docs.descriptor.d.ts","sourceRoot":"","sources":["../../src/docs/sync.docs.descriptor.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AAE7D,QAAA,MAAM,UAAU,EAAE,mBAoRjB,CAAC;AAEF,eAAe,UAAU,CAAC"}
+{"version":3,"file":"sync.docs.descriptor.d.ts","sourceRoot":"","sources":["../../src/docs/sync.docs.descriptor.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,6BAA6B,CAAC;AAEvE,QAAA,MAAM,UAAU,EAAE,mBA0QjB,CAAC;AAEF,eAAe,UAAU,CAAC"}