Initial Commit

openspec/changes/enterprise-api-plugin-database/proposal.md

@@ -0,0 +1,82 @@
+# OpenSpec Change: enterprise-api-plugin-database
+
+- **Change ID**: enterprise-api-plugin-database
+- **Package**: `@suaveplan/api-plugin-database`
+- **Category**: api/data
+- **Target path**: `api/data/api-plugin-database`
+- **Status**: PROPOSED
+- **Date**: 2026-04-24
+- **Reference spec**: `/mnt/s/web/suaveplan/enterprise/api-plugin-database.md`
+
+---
+
+## Summary
+
+Deliver `@suaveplan/api-plugin-database` on the genesis branch from scratch at enterprise quality. Foundation database plugin for the API tier: wraps `@suaveplan/surrealdb` (or any `DatabaseAdapter`-compatible backend), provides `getDb()` helper for downstream plugins, runs SurrealQL migrations at boot, exposes a `/health/db` readiness probe, and registers a `DatabaseService` with connection-pool stats. This is the dependency declared by almost every other plugin; it must land first in the dependency wave. Events: `database:connected`, `database:error`.
+
+---
+
+## Available workspace deps on genesis
+
+| Package | Role |
+|---|---|
+| `@suaveplan/api` (`workspace:^`) | `definePlugin` |
+| `@suaveplan/api-shared` (`workspace:^`) | Helpers |
+| `@suaveplan/db` (`workspace:^`) | `DatabaseAdapter` interface |
+| `@suaveplan/error` (`workspace:^`) | `DatabasePluginError` hierarchy |
+| `@suaveplan/types` (`workspace:^`) | `LoggerLike` |
+| `@suaveplan/events` (`workspace:^`) | Event bus |
+| `@suaveplan/logger` (`workspace:^`) | Structured logging |
+| `hono` + `@hono/zod-openapi` + `zod` | Routes |
+| `@opentelemetry/api` | OTel |
+
+---
+
+## Public API surface
+
+```ts
+function createDatabasePlugin(config: DatabasePluginConfig): PluginDescriptor<DatabasePluginConfig>
+
+// Registered service accessible by downstream plugins:
+interface DatabaseService {
+  getDb(): DatabaseAdapter
+  runMigrations(path: string): Promise<MigrationResult>
+  healthCheck(): Promise<{ status: 'ok' | 'degraded'; latencyMs: number }>
+  getStats(): DatabaseStats
+}
+
+interface DatabasePluginConfig {
+  adapter: DatabaseAdapter   // injected; typically @suaveplan/surrealdb
+  migrationsBasePath?: string
+}
+```
+
+### Error codes
+
+```ts
+type DatabasePluginErrorCode =
+  | "DB_CONNECTION_FAILED"
+  | "DB_MIGRATION_FAILED"
+  | "DB_HEALTH_CHECK_FAILED"
+  | "DB_NOT_INITIALIZED"
+```
+
+---
+
+## File layout
+
+```text
+api/data/api-plugin-database/
+  package.json  tsconfig.json  vitest.config.ts
+  src/
+    index.ts  events.ts  types/  errors/
+    services/database/
+    routes/health/
+  tests/integration.test.ts
+```
+
+---
+
+## Impact
+
+This is the most critical dependency: every other plugin with `dependencies: ["database"]` requires this plugin. Must be published first. Prerequisites: `@suaveplan/api`, `@suaveplan/db`, `@suaveplan/error`, `@suaveplan/events`, `@suaveplan/logger`.

openspec/changes/enterprise-api-plugin-database/tasks.md

@@ -0,0 +1,55 @@
+# Tasks: enterprise-api-plugin-database
+
+**Change ID**: enterprise-api-plugin-database
+**Package**: `@suaveplan/api-plugin-database`
+**Target path**: `api/data/api-plugin-database`
+**Prerequisite packages on Verdaccio**: `@suaveplan/api`, `@suaveplan/api-shared`, `@suaveplan/db`, `@suaveplan/error`, `@suaveplan/events`, `@suaveplan/logger`, `@suaveplan/types`
+
+---
+
+## 0. Pre-flight (non-negotiable)
+
+- [ ] 0.1 Confirm clean working tree (`git status` reports nothing) and no in-flight worktrees with uncommitted work (`git worktree list` then `git status` in each)
+- [ ] 0.2 If any worktrees exist under `.claude/worktrees/`, account for each one: still-active agent, work-pending-merge, or stale-and-prune. Stale worktrees MUST be removed (`git worktree remove`) before opening a new one — code that has been lost twice on main is the failure mode this guards against.
+- [ ] 0.3 Confirm the package set in `MANIFEST.md` matches `find packages -maxdepth 3 -name package.json` count. Drift here means a prior change archived without regenerating the manifest.
+
+## 1. Scaffold + types + errors + events
+
+- [ ] Create `api/data/api-plugin-database/`; `package.json` v0.0.0, `"sideEffects": ["src/events.ts"]`; standard tooling.
+- [ ] Types: `DatabasePluginConfig` (Zod), `DatabaseStats`, `MigrationResult`.
+- [ ] Errors: 4-code union + metadata + registration. Test + doc.
+- [ ] Events: `DatabaseEventMap` (database:connected, database:error, database:migration:complete).
+
+---
+
+## 2. DatabaseService (`.test.ts` + `.md`)
+
+- [ ] `getDb()` — returns `DatabaseAdapter`; throws `DatabasePluginError(DB_NOT_INITIALIZED)` if called before `onInit`.
+- [ ] `runMigrations(path)` — reads `.surql` files from path ordered by filename; executes each idempotently; returns `MigrationResult`.
+- [ ] `healthCheck()` — executes a lightweight query; measures latency; emits `database:error` on failure.
+- [ ] `getStats()` — returns connection count, query count from adapter internals.
+- [ ] OTel span on each method.
+
+---
+
+## 3. Health route
+
+- [ ] `GET /health/db` — calls `healthCheck()`; returns 200 `{status: "ok"}` or 503 `{status: "degraded"}`.
+- [ ] `health.test.ts` + `health.md`.
+
+---
+
+## 4. Plugin factory
+
+- [ ] `createDatabasePlugin(config)`: `definePlugin` with name `"database"`, no dependencies.
+- [ ] `onInit`: open DB connection; run migrations at `config.migrationsBasePath`; register `DatabaseService`; emit `database:connected`.
+- [ ] `onClose`: close DB connection; emit `database:disconnected`.
+
+---
+
+## 5. Integration tests + publish
+
+- [ ] Connect to real SurrealDB; run sample migrations; health-check returns ok; stats non-zero.
+- [ ] `bunx turbo lint typecheck test --filter=@suaveplan/api-plugin-database` — green; 100% coverage.
+- [ ] `bun scripts/publish.ts --package @suaveplan/api-plugin-database`.
+- [ ] Archive → `openspec/archive/2026-04-24-enterprise-api-plugin-database/`.