@vibesdotdev/storage 0.0.1 → 0.0.2

package/README.md

@@ -1,75 +1,22 @@
 # @vibesdotdev/storage
 
-Universal storage primitive. Defines `storage/manifest` and `storage/adapter`
-runtime kinds, the `StorageManifest<T>` base, and the sync/policy/record
-abstractions. Adapters live in sibling packages and register themselves.
+Storage manifests, record contracts, and runtime descriptors for Vibes data adapters.
 
-## Quickstart
+This package is part of the public Vibes framework package set. The source repository is private while the public repository split is being prepared, so package documentation is published on the Vibes docs site.
 
-### Define a storage manifest
+## Install
 
-```ts
-import { z } from 'zod';
-import { createStorageManifest } from '@vibesdotdev/storage/manifest';
-
-export const sessions = createStorageManifest({
-  id: 'auth.sessions',
-  namespace: 'auth',
-  schema: z.object({
-    id: z.string(),
-    userId: z.string(),
-    expiresAt: z.string().datetime(),
-  }),
-  adapters: ['localdb', 'cloud-api'],
-});
-```
-
-### Load + save through the runtime
-
-```ts
-import { StorageManifest } from '@vibesdotdev/storage';
-
-const sessions = new StorageManifest('auth.sessions');
-await sessions.put({ id: 's1', userId: 'u1', expiresAt: '2026-12-31T00:00:00Z' });
-const session = await sessions.get('s1');
+```sh
+bun add @vibesdotdev/storage
+# or
+npm install @vibesdotdev/storage
 ```
 
-The runtime selects the adapter (`localdb` consumer-side, `cloud-api`
-cloud-side) based on scope. Feature code never branches on hardware.
-
-### Sync (local-first)
-
-When sync is enabled in runtime config, consumer writes mirror to the cloud
-adapter via `cloud-sync.consumer`. Sync state is tracked in a separate
-manifest so divergent writes are reconciled rather than silently merged.
-
-## Adapters
+## Documentation
 
-Storage core ships zero adapter implementations. Apps load the adapter
-packages their scope can support:
-
-- [`@vibesdotdev/storage-adapter-memory`](../storage-adapter-memory/) — tests/ephemeral
-- [`@vibesdotdev/storage-adapter-json`](../storage-adapter-json/) — local file-backed
-- [`@vibesdotdev/storage-adapter-localdb`](../storage-adapter-localdb/) — SQLite (Bun)
-- [`@vibesdotdev/storage-adapter-cloud-api`](../storage-adapter-cloud-api/) — hosted
-- [`@vibesdotdev/storage-adapter-drizzle`](../storage-adapter-drizzle/) — SQL via Drizzle
-- External integrations (SharePoint, etc.) → [`platform`](../platform/SPEC.md)
-
-## CLI
-
-```bash
-vibes storage list
-vibes storage status
-vibes storage sync run
-```
-
-## Test
-
-```bash
-bun run test
-```
+- Package guide: https://docs.vibes.dev/packages/storage
+- Vibes docs: https://docs.vibes.dev
 
-## Docs
+## License
 
-- [SPEC.md](./SPEC.md) — package contract, owned surfaces, hard rules
-- [runtime](../runtime/SPEC.md), [config](../config/SPEC.md)
+MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vibesdotdev/storage",
-  "version": "0.0.1",
+  "version": "0.0.2",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -190,17 +190,12 @@
     "registry": "https://registry.npmjs.org",
     "access": "public"
   },
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/vibesdotdev/monorepo.git",
-    "directory": "packages/storage"
-  },
   "peerDependencies": {
-    "@vibesdotdev/runtime": "0.0.1"
+    "@vibesdotdev/runtime": "0.0.2"
   },
   "dependencies": {
-    "@vibesdotdev/logging": "0.0.1",
-    "@vibesdotdev/runtime-plugin-types": "0.0.1",
+    "@vibesdotdev/logging": "0.0.2",
+    "@vibesdotdev/runtime-plugin-types": "0.0.2",
     "zod": "^4.3.6"
   },
   "scripts": {
@@ -216,7 +211,6 @@
     "src",
     "bin",
     "README.md",
-    "SPEC.md",
     "LICENSE",
     "!src/**/__tests__/**",
     "!src/**/__stubs__/**",
@@ -237,5 +231,10 @@
   ],
   "vibes": {
     "visibility": "public-framework"
+  },
+  "description": "Storage manifests, record contracts, and runtime descriptors for Vibes data adapters.",
+  "homepage": "https://docs.vibes.dev/packages/storage",
+  "bugs": {
+    "url": "https://docs.vibes.dev/packages/storage#support"
   }
 }

package/SPEC.md

@@ -1,60 +0,0 @@
-# @vibesdotdev/storage
-
-Runtime-resolved persistence. Universal core: defines the kinds, manifest base, sync/policy/record abstractions. Adapters live in sibling packages and register themselves.
-
-## Owns
-
-- **Runtime kinds:**
-  - `storage/adapter` — storage backends (impls live in sibling adapter packages). Descriptors carry a coarse-grained `capabilities: ('list'|'read'|'write'|'browse')[]` array (default `['read','write']`); adapters declaring `'browse'` implement `listDrives() → StorageDrive[]` + `list(driveId, path) → StorageEntry[]`.
-  - `storage/manifest` — storable data type definitions; default impl `StorageManifest`
-  - `storage/record` — single-table CRUD with relations, indexes, FTS, migrations, computed fields, hierarchy, and side effects
-  - `storage/sync-bridge` — declarative runtime-kind ↔ cloud-CRUD sync wiring (server/CLI only; no default impl)
-- **`StorageManifest<T>`** (`./manifest`): base manifest, source-policy, cloud-sync handoff (`cloud-sync.consumer` — universal; uses runtime to resolve cloud adapter)
-- **Interfaces** (`./interfaces`): adapter, document-store, key-value, repository, record, schema, and `StorageConsumerFs` TS contracts. `StorageAdapterInterface` declares optional `listDrives()` and `list(driveId, path)` methods for `browse`-capable adapters.
-- **Schemas** (`./schemas`): Zod schemas for adapter / manifest / record / schema / sync-bridge descriptors, plus the rich record-descriptor surface (relations, indexes, FTS, migrations, computed fields, hierarchy, side effects) and the multi-table `StorageSchemaDescriptor`. Also exports `StorageEntrySchema`, `StorageDriveSchema`, and `StorageCapabilitySchema` for use by browse-capable adapters and consumers.
-- **Client surface** (`./client`): `listBrowsableStorageAdapters()` — synchronous helper that queries the runtime for every `storage/adapter` descriptor with `'browse'` in `capabilities`. Consumed by picker UIs (AI model sources, knowledge corpora, etc.). Does not load implementations.
-- **Record events** (`./record/events`): `storage.record.afterCreate`, `storage.record.afterUpdate`, `storage.record.afterDelete` — registered as descriptors by the plugin
-- **Sync** (`./sync`): sync-bridge, record-sync-bridge, cloud-pull, sync-manifest, sync-state, resolve-sync-target — all runtime-resolved, no adapter imports
-- **Policy** (`./policy`): storage policy / overrides / persistence / context / types, plus `storage-policy.context.descriptor` (universal descriptor) and `storage-policy.context.server` (server-side loader; registered via plugin `onRegister`)
-- **Record** (`./record`): base record class (`StorageRecord`), events, extensions
-- **Resolver** (`./resolver/storage-backed-resolver`): resolves arbitrary kinds whose data lives in either a `storage/manifest` or a `config/manifest`
-- **Bridge** (`./bridge`): `storage-kind-bridge` + `bridgeStorageKinds` helper that hydrates feature kinds from their backing storage manifests
-- **CLI** (`./cli`): `vibes storage` and `vibes storage sync` groups; commands `storage list`, `storage sync pull`, `storage sync push`, `storage sync status`, `storage sync resolve` — all query the runtime, never import adapters
-- **TUI** (`./tui`): `storage.explorer` (`tui/app`) and `storage.open` (`tui/command`) — registered conditionally by plugin `onRegister` when the `tui/*` kinds are loaded
-- **Daemon commands** (`./daemon/commands`): storage RPC verbs `sync.status`, `sync.trigger`, `sync.resolve` using runtime-plugin types, self-contained implementations
-- **Paths** (`./paths`): canonical storage path resolution (string-only, no FS)
-- **Plugin** (`./storage.plugin` = `./plugin`): registers the four runtime kinds, the CLI groups + commands, and the record-event descriptors. `onRegister` additionally wires the storage-policy context loader and (when `tui/app` / `tui/command` are present) the TUI explorer + open implementations.
-
-## Does not own
-
-- **Adapter implementations.** Each adapter is its own package: [`storage-adapter-json`](../storage-adapter-json/), [`storage-adapter-localdb`](../storage-adapter-localdb/), [`storage-adapter-memory`](../storage-adapter-memory/), [`storage-adapter-cloud-api`](../storage-adapter-cloud-api/), [`storage-adapter-drizzle`](../storage-adapter-drizzle/). They each register `storage/adapter` descriptors when imported.
-- **External-integration adapters** (SharePoint, etc.) → the owning integration package (e.g. [`integrations-microsoft`](../integrations-microsoft/SPEC.md) registers the `sharepoint` adapter alongside the Microsoft 365 integration providers).
-- **Server DB connection helper.** Lives in [`storage-adapter-drizzle`](../storage-adapter-drizzle/SPEC.md) (`./db` subpath), co-located with the Drizzle persistence factory.
-- **Encryption primitive** → [`config/services`](../config/SPEC.md). Encrypted adapters consume it.
-- **Configuration modeling** → [`config`](../config/SPEC.md).
-- **Domain-specific manifests** (chat history, AI artifacts, knowledge sources, account tables, etc.). Each owning module declares its own `storage/manifest` descriptors.
-- **Module-level client** (`runtime/client`). Storage is consumed via `StorageManifest<T>` instances and runtime kind resolution directly.
-
-## Hard rules
-
-- **The core package is universal.** No Node/Bun/SQL/HTTP imports in core. Anything that breaks browser or Cloudflare bundles belongs in an adapter package.
-- **All persistence goes through `StorageManifest<T>`.** No direct adapter calls in features.
-- **Adapter selection is runtime-resolved.** Manifests declare allowed adapters; runtime picks one via scope (`hardware`, `qualifiers: { storage }`). Features do not branch on `isCloud`/`connectionMode`.
-- **Local-first writes can mirror to cloud** when sync is enabled. Sync state is tracked separately; do not silently merge divergent writes.
-- **Adapter package contract:** each `storage-adapter-{name}` package exports a plugin that registers a `storage/adapter` descriptor + impl. Apps load the adapter packages their scope can support. The core never imports adapter packages.
-- **CLI / TUI / daemon descriptors here query the runtime; they do not import adapters.**
-
-## Public entrypoints
-
-Canonical entrypoints: `.`, `./manifest`, `./manifest/*`, `./interfaces`, `./interfaces/record`, `./interfaces/schema`, `./interfaces/*`, `./schemas`, `./schemas/record`, `./schemas/schema`, `./schemas/*`, `./sync`, `./sync/*`, `./record`, `./record/base`, `./record/*`, `./bridge`, `./bridge/types`, `./client`, `./client/*`, `./resolver/*`, `./cli/*`, `./tui/*`, `./daemon/commands/*`, `./paths`, `./plugin` (= `./storage.plugin`).
-
-## Verification
-
-`bun run test` from package root (runs `test:isolated` + `test:main`). Covers manifest base, sync state + bridge, policy, record, resolver, schemas, interfaces, and TUI descriptors. Adapter-specific tests live in each adapter package.
-
-## Links
-
-- [runtime/SPEC.md](../runtime/SPEC.md)
-- [config/SPEC.md](../config/SPEC.md)
-- [storage-adapter-drizzle](../storage-adapter-drizzle/)
-- [platform/SPEC.md](../platform/SPEC.md)