first commit

2026-05-29 08:20:56 +01:00
commit 949299f58d
6368 changed files with 527176 additions and 0 deletions
--- a/plugins/library-navigator/skills/sp-better-auth-surrealdb/SKILL.md
+++ b/plugins/library-navigator/skills/sp-better-auth-surrealdb/SKILL.md
@@ -0,0 +1,100 @@
+---
+name: sp-better-auth-surrealdb
+description: Better-Auth Adapter for SurrealDB v3 — 17-table schema, Where[]→SurrealQL compilation, record-link prefixing, id strategies, conformance harness.
+---
+
+# Architecture
+
+| Component | Responsibility |
+|---|---|
+| `createBetterAuthSurrealAdapter` | Returns 10-method Better-Auth `Adapter` (create/find/update/delete/count) |
+| `betterAuthSurrealAdapter` | v1.6 integration surface wrapping `createAdapterFactory` |
+| `compileWhere` | Translates Better-Auth `Where[]` filters to parameterised SurrealQL `WHERE` |
+| `compileSelect` | Compiles `select?: string[]` projection into SurrealQL column list |
+| `compileSortBy` | Compiles `sortBy` into SurrealQL `ORDER BY` fragment |
+| `applyLinkPrefix` / `stripLinkPrefix` | Auto-prefixes record-link fields on write, strips on read |
+| `prepareCreate` / `normaliseReturnedId` | Id strategy handlers: `record-id` (default), `plain`, `ulid` |
+| `applyBetterAuthSchema` / `BETTER_AUTH_SURREAL_SCHEMA` | Bundled canonical 17-table SurrealQL schema |
+| `createInMemoryKeyStore` | In-memory JWKS storage with rotation and expiration |
+| `BETTER_AUTH_SURREALDB_CODES` + `BetterAuthSurrealError` | Structured error registry |
+| `instrument` | OTel instrumentation wrapper for adapter operations |
+| `runAdapterConformance` | Reusable conformance test harness |
+
+## File Structure
+
+```
+packages/identity/auth/better-auth-surrealdb/src/
+  adapter/            createBetterAuthSurrealAdapter, betterAuthSurrealAdapter (v1.6), internals, operations
+  compile/            compileWhere, compileSelect, compileSortBy
+  id-strategy/        prepareCreate, normaliseReturnedId, generateUlid
+  link-fields/        applyLinkPrefix, stripLinkPrefix, DEFAULT_BETTER_AUTH_LINK_FIELDS
+  schema/             BETTER_AUTH_SURREAL_SCHEMA, applyBetterAuthSchema
+  schemas/            Zod schemas for options and link field maps
+  error-codes/        BETTER_AUTH_SURREALDB_CODES and BetterAuthSurrealError
+  otel/               instrument, AdapterOutcome, resetInstrumentsForTesting
+  types/              TypeScript interfaces (BetterAuthSurrealAdapterOptions, Row, etc.)
+  testing/            runAdapterConformance harness
+```
+
+## Sibling packages
+
+- `@suaveplan/surrealdb` — SurrealAdapter for database operations
+- `@suaveplan/testing-integration-surrealdb` — SurrealDB container fixture for conformance tests
+- `@suaveplan/error` — structured error registry via `defineCodes`
+- `@suaveplan/types` — shared TypeScript primitives
+
+## Patterns
+
+### Quick Start (v1.6)
+
+```ts
+import { SurrealAdapter } from "@suaveplan/surrealdb";
+import { applyBetterAuthSchema } from "@suaveplan/better-auth-surrealdb/schema";
+import { betterAuthSurrealAdapter } from "@suaveplan/better-auth-surrealdb/adapter/v1.6";
+import { betterAuth } from "better-auth";
+
+const client = new SurrealAdapter({ url: "ws://localhost:8000", namespace: "auth", database: "auth", username: "root", password: process.env.SURREAL_PASSWORD });
+await client.connect();
+await applyBetterAuthSchema(client);
+
+export const auth = betterAuth({
+  database: betterAuthSurrealAdapter({ client }),
+  secret: process.env.BETTER_AUTH_SECRET,
+  baseURL: "http://localhost:3000",
+  emailAndPassword: { enabled: true },
+});
+```
+
+### Direct adapter (v1.4 shape)
+
+```ts
+import { createBetterAuthSurrealAdapter } from "@suaveplan/better-auth-surrealdb/adapter";
+
+const adapter = createBetterAuthSurrealAdapter({ client });
+await adapter.create({ model: "user", data: { id: "u1", email: "a@b" } });
+```
+
+### Custom link fields
+
+```ts
+createBetterAuthSurrealAdapter({
+  client,
+  linkFields: { session: { userId: "user" }, member: { userId: "user", organizationId: "tenant" } },
+});
+```
+
+## Constraints
+
+- Peer dependency on `better-auth` ^1.4.0 (type-only at package boundary)
+- SurrealDB v3 required (uses `record<target>` typed links)
+- Default id strategy is `record-id`; rejects ids containing `:`
+- Schema version moves in lockstep with package version
+- Conformance harness requires Docker SurrealDB container
+
+## Checklist
+
+- [ ] Verify adapter implements all 10 Better-Auth Adapter methods
+- [ ] Confirm `BETTER_AUTH_SURREALDB_CODES` registered via `defineCodes`
+- [ ] Check subpath exports in `package.json` align with `src/` modules
+- [ ] Run `bunx turbo lint typecheck test build --filter=@suaveplan/better-auth-surrealdb`
+- [ ] Confirm conformance harness passes against SurrealDB container