@vibesdotdev/localdb 0.0.1 → 0.0.2

package/README.md

@@ -1,121 +1,22 @@
 # @vibesdotdev/localdb
 
-Local SQLite primitive for the vibes consumer-hardware toolkit. Owns the
-connection pool, namespace migration registry, recovery/trapdoor flow, and the
-`vibes dev localdb` CLI surface. Backed by `bun:sqlite`; server-runtime only.
+Local SQLite storage helpers and migration utilities for Vibes development surfaces.
 
-The contract lives in [`SPEC.md`](./SPEC.md). Operational status lives in
-[`PROD-CHECKLIST.md`](./PROD-CHECKLIST.md). This README is the developer
-quick-start.
+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.
 
 ## Install
 
-Workspace-only:
-
-```jsonc
-// package.json
-{
-  "dependencies": {
-    "@vibesdotdev/localdb": "workspace:*",
-    "@vibesdotdev/runtime": "workspace:*"
-  }
-}
-```
-
-## Register migrations and open a database
-
-A domain module declares its migrations once and asks for its database by
-namespace + path. Migrations run on first `getDatabase()` for that
-`namespace:path`.
-
-```ts
-import { localdb, type Migration } from '@vibesdotdev/localdb';
-import type { Database } from 'bun:sqlite';
-
-const MY_MIGRATIONS: Migration[] = [
-  {
-    version: 1,
-    name: 'Create things table',
-    up: (db: Database) => {
-      db.exec(`
-        CREATE TABLE IF NOT EXISTS things (
-          id TEXT PRIMARY KEY,
-          created_at TEXT NOT NULL DEFAULT (datetime('now'))
-        )
-      `);
-    }
-  }
-];
-
-localdb.registerMigrations('my-module', MY_MIGRATIONS);
-
-const handle = await localdb.getDatabase(
-  'my-module',
-  '.vibes/my-module/state.db',
-  'my-module-storage'
-);
-
-const db = handle.getDatabase();
-db.query('INSERT INTO things (id) VALUES (?)').run('hello');
-```
-
-Migration versions must be `1..N` consecutive — registering out of order
-throws. Asking for an unregistered namespace throws. Migration failure
-triggers automatic recovery: the corrupted file is backed up
-(`*.bak-{ts}`, last 12 retained) and a fresh database is migrated from
-version 0.
-
-## Get a raw connection (no migrations)
-
-For quick read-only tools or one-off scripts that don't need version
-management, `getRawDatabase` returns a pooled `bun:sqlite.Database` directly:
-
-```ts
-import { localdb } from '@vibesdotdev/localdb';
-
-const raw = localdb.getRawDatabase('.vibes/scratch/log.db', 'log-reader');
-const rows = raw.query('SELECT * FROM events ORDER BY ts DESC LIMIT 100').all();
-```
-
-This bypasses the migration registry. Prefer `getDatabase()` for any
-schema-owning code.
-
-## CLI
-
-The package registers `vibes dev localdb` for inspecting state from a
-terminal:
-
 ```sh
-vibes dev localdb status         # connection + migration status across namespaces
-vibes dev localdb namespaces     # registered migration namespaces
-vibes dev localdb pools          # connection pool statistics
-vibes dev localdb migrate <ns>   # run pending migrations for a namespace
-vibes dev localdb query <ns>     # raw SQL against a namespace database
+bun add @vibesdotdev/localdb
+# or
+npm install @vibesdotdev/localdb
 ```
 
-Commands run on consumer hardware only.
-
-## What lives where
-
-- The `storage/adapter` impl `storage.localdb.core` →
-  [`@vibesdotdev/storage-adapter-localdb`](../storage-adapter-localdb/) (the
-  thin storage wrapper that consumes this package).
-- App and feature schemas / migration SQL → the owning package or app.
-  This package owns the SQLite *primitive*; it does not carry domain SQL.
-- Cloud / multi-tenant SQLite → use
-  [`@vibesdotdev/storage-adapter-drizzle`](../storage-adapter-drizzle/)
-  with libsql/Turso or D1.
+## Documentation
 
-## Verification
-
-```sh
-bun test packages/localdb
-bun --bun tsc -p packages/localdb/tsconfig.json --noEmit
-```
+- Package guide: https://docs.vibes.dev/packages/localdb
+- Vibes docs: https://docs.vibes.dev
 
-## Links
+## License
 
-- [SPEC.md](./SPEC.md) — package contract.
-- [storage](../storage/SPEC.md),
-  [storage-adapter-localdb](../storage-adapter-localdb/),
-  [storage-adapter-drizzle](../storage-adapter-drizzle/SPEC.md).
+MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vibesdotdev/localdb",
-  "version": "0.0.1",
+  "version": "0.0.2",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -100,15 +100,10 @@
     "registry": "https://registry.npmjs.org",
     "access": "public"
   },
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/vibesdotdev/monorepo.git",
-    "directory": "packages/localdb"
-  },
   "peerDependencies": {
-    "@vibesdotdev/runtime": "0.0.1",
-    "@vibesdotdev/logging": "0.0.1",
-    "@vibesdotdev/cli": "0.0.1"
+    "@vibesdotdev/runtime": "0.0.2",
+    "@vibesdotdev/logging": "0.0.2",
+    "@vibesdotdev/cli": "0.0.2"
   },
   "scripts": {
     "test": "bun test",
@@ -121,7 +116,6 @@
     "src",
     "bin",
     "README.md",
-    "SPEC.md",
     "LICENSE",
     "!src/**/__tests__/**",
     "!src/**/__stubs__/**",
@@ -142,5 +136,10 @@
   ],
   "vibes": {
     "visibility": "public-framework"
+  },
+  "description": "Local SQLite storage helpers and migration utilities for Vibes development surfaces.",
+  "homepage": "https://docs.vibes.dev/packages/localdb",
+  "bugs": {
+    "url": "https://docs.vibes.dev/packages/localdb#support"
   }
 }

package/SPEC.md

@@ -1,119 +0,0 @@
-# @vibesdotdev/localdb
-
-Local SQLite primitive for the vibes consumer-hardware toolkit. Owns the
-connection pool (one `bun:sqlite` `Database` per file path, WAL mode, busy
-timeout, ref-counted, idle-cleanup), the namespace migration registry
-(sequential-version enforcement, legacy `PRAGMA user_version` bootstrap,
-`vibes_schema_versions` tracking table), the recovery/trapdoor flow (backup →
-delete → recreate → re-migrate on migration failure or version mismatch), and
-the `vibes dev localdb` CLI surface. Consumer hardware only — `bun:sqlite` is
-server-runtime only. The storage adapter that wraps localdb lives in a sibling
-adapter package, not here.
-
-## Owns
-
-- **Plugin descriptors registered by the plugin** (`./plugin`):
-  - `runtime/context` `dev/localdb` — server-side `LocaldbApi` access for
-    runtime callers.
-  - `cli/group` `dev.localdb` parented under `dev` — `vibes dev localdb`.
-  - `cli/command` `dev.localdb.{status,migrate,namespaces,pools,query}`.
-- **Connection pool** (`./core/connection-pool`): per-path pooled `bun:sqlite`
-  `Database`, ref-counting, idle stale-cleanup (30 min), uniform PRAGMAs
-  (`journal_mode=WAL`, `busy_timeout=5000`, `foreign_keys=ON`,
-  `synchronous=NORMAL`, `temp_store=MEMORY`).
-- **Migration registry** (`./core/migration-registry`): namespace-keyed
-  `Migration[]`, sequential `1..N` version enforcement,
-  `vibes_schema_versions` tracking, legacy `PRAGMA user_version` one-time
-  bootstrap, incompatible-database (version-too-high) detection.
-- **`LocalDatabase` + `localdb` singleton manager** (`./core/database`):
-  per-`namespace:path` entry caching with per-`dbPath` async lock,
-  recovery/trapdoor on migration failure with retained backups (last 12),
-  `getRawDatabase()` for migration-free pooled access, `closeAll()` /
-  process-exit cleanup.
-- **Public API types** (`./schemas`): `LocaldbApi`, `LocaldbRawDatabase`,
-  `LocaldbStatement`, `Migration`, `MigrationFunction`, `ConnectionStats`,
-  `ConnectionPoolApi`, `MigrationRegistryApi`.
-
-## Does not own
-
-- The `storage/adapter` impl `storage.localdb.core` →
-  [`storage-adapter-localdb`](../storage-adapter-localdb/SPEC.md). Per pattern
-  1, environment-specific storage adapters live in sibling packages; the
-  adapter is a thin `storage` consumer of `localdb`.
-- Domain migration SQL → owning module:
-  - `atlas` schema → [`workspace`](../workspace/SPEC.md) (the only registrar,
-    via `packages/workspace/src/codegraph/storage/register-migrations.ts`).
-  - `pm-state` schema → [`pm`](../pm/SPEC.md) (already lives there; PM passes
-    its own dir as an absolute path to `loadMigrationSQLSync`).
-  - `external` `file_accesses` → [`external`](../external/SPEC.md) (already
-    inline-defined in `packages/external/src/register-migrations.ts`).
-  - `config` schema → [`cli`](../cli/SPEC.md) (its app-config storage
-    subsystem already declares the namespace).
-- Cross-process / multi-tenant locking, replication, observability of pool
-  stats. Out of scope for the consumer-hardware floor; cloud storage uses
-  [`storage-adapter-drizzle`](../storage-adapter-drizzle/SPEC.md).
-- A `runtime/client` descriptor or `getVibesLocaldbClient()`. LocalDB is a
-  runtime substrate consumed via the `localdb` singleton or the `dev/localdb`
-  context, not a domain module.
-
-## Hard rules
-
-- **`bun:sqlite`, server-runtime only.** All filesystem/SQLite imports are
-  dynamic and gated on `isLocaldbServerRuntime()`. `LocalDatabase.initialize()`
-  throws in browser bundles.
-- **Sequential migration versions.** Registered migrations form `1..N` with
-  no gaps; out-of-sequence registration throws at `register()` time.
-- **Unknown namespace = throw.** `needsMigration` / `runMigrations` /
-  `getDatabase` against an unregistered namespace is a hard failure (per
-  pattern 4); domain modules call
-  `localdb.registerMigrations(namespace, migrations)` before opening their
-  database.
-- **Recovery is automatic and lossy.** Migration failure or
-  version-higher-than-registered triggers backup (`*.bak-{ts}`, last 12
-  retained) → delete file + WAL/SHM artifacts → fresh DB → re-run migrations
-  from version 0. Domain code must not rely on data surviving migration
-  failure.
-- **One Database per file path.** All access goes through the pool; the
-  `usePool: false` direct-connection path stays for special cases but new
-  code uses the pool.
-- **No domain SQL in this package.** Migration SQL files for a feature live
-  with that feature's package.
-
-## Migration debt
-
-All items completed in t11-mig-localdb-final-and-seal. See git history for original debt items.
-
-## Public entrypoints
-
-`.` — root exports (`localdb`, `LocalDatabase`, `Migration`, etc.)
-`./plugin` — LocalDB plugin registration
-`./schemas` — TypeScript type definitions (`LocaldbApi`, `Migration`, etc.)
-
-Migration-era subpaths (`./core/*`, `./migrations/*`, `./localdb.plugin`) have been removed.
-
-## Verification
-
-`bun test` from `packages/localdb`. Covers `MigrationRegistry` (version
-tracking, sequence validation, legacy-bootstrap, incompatible-version
-detection), `ConnectionPool` (pooling, ref-count, stats), `LocalDatabase`
-(init / idempotence / recovery / backup pruning), `localdb` manager
-(namespace caching + per-path lock), and `loadMigrationSQL` file resolution.
-Today (per `PROD-CHECKLIST.md` 2026-04-18): 79 pass / 0 fail.
-
-## Links
-
-- [storage/SPEC.md](../storage/SPEC.md),
-  [storage-adapter-localdb/SPEC.md](../storage-adapter-localdb/SPEC.md),
-  [storage-adapter-drizzle/SPEC.md](../storage-adapter-drizzle/SPEC.md),
-  [runtime/SPEC.md](../runtime/SPEC.md),
-  [cli/SPEC.md](../cli/SPEC.md),
-  [logging/SPEC.md](../logging/SPEC.md)
-- Active consumers: [pm](../pm/SPEC.md), [workspace](../workspace/SPEC.md),
-  [external](../external/SPEC.md), [cli](../cli/SPEC.md),
-  [presence](../presence/SPEC.md), [prompts](../prompts/SPEC.md),
-  [experiments](../experiments/SPEC.md), [desktop](../desktop/SPEC.md),
-  [browser-automation](../browser-automation/SPEC.md),
-  [knowledge](../knowledge/SPEC.md), [setup](../setup/SPEC.md)
-- Doctrine:
-  [RUNTIME-FIRST-MODULES.md](../../docs/architecture/RUNTIME-FIRST-MODULES.md),
-  [RUNTIME-SCOPE-TOPOLOGY.md](../../docs/architecture/RUNTIME-SCOPE-TOPOLOGY.md)