@yottagraph-app/aether-instructions 1.1.15 → 1.1.16

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@yottagraph-app/aether-instructions",
-    "version": "1.1.15",
+    "version": "1.1.16",
     "description": "Cursor rules, commands, and skills for Aether development",
     "files": [
         "rules",

package/rules/server.mdc

@@ -19,7 +19,8 @@ server/
 │   ├── kv/                  # KV (Upstash Redis) CRUD — read, write, delete, documents, status
 │   └── avatar/[url].ts      # Avatar image proxy
 └── utils/
-    ├── redis.ts              # Upstash Redis client init (from Vercel KV env vars)
+    ├── redis.ts              # Upstash Redis client (lazy-init from KV_REST_API_URL)
+    ├── neon.ts               # Neon Postgres client (lazy-init from DATABASE_URL) — present if Neon provisioned
     └── cookies.ts            # Cookie handling (@hapi/iron)
 ```
 
@@ -69,33 +70,22 @@ Returns `null` if KV is not configured (env vars missing). Always check.
 
 ## Neon Postgres
 
-If a Neon database is connected to the project, `DATABASE_URL` (pooled) and
-`DATABASE_URL_UNPOOLED` (direct) are available. Vercel auto-injects them for
-deployed builds; for local dev they are populated in `.env` during project
-init. Check `.env` for `DATABASE_URL` — if present, Postgres is ready to use.
+If `DATABASE_URL` is in `.env`, Postgres is ready to use. The project init
+scaffolds `server/utils/neon.ts` and installs `@neondatabase/serverless`
+automatically when a Neon database is detected.
 
-### Utility pattern
+### How to check
 
-Create `server/utils/neon.ts` following the same lazy-init pattern as
-`redis.ts` — export a getter that returns `null` when the env var is missing:
+- `DATABASE_URL` present in `.env` → Postgres is connected
+- `server/utils/neon.ts` exists → utility is scaffolded
+- If either is missing, the project wasn't provisioned with Neon (add it
+  from the Broadchurch Portal, then re-run `node init-project.js`)
 
-```typescript
-import { neon, type NeonQueryFunction } from '@neondatabase/serverless';
+### Usage
 
-let _sql: NeonQueryFunction | null = null;
-
-export function getDb(): NeonQueryFunction | null {
-  if (_sql) return _sql;
-  const url = process.env.DATABASE_URL;
-  if (!url) return null;
-  _sql = neon(url);
-  return _sql;
-}
-```
-
-Install the driver: `npm install @neondatabase/serverless`
-
-### Usage in server routes
+`server/utils/neon.ts` exports `getDb()` (same lazy-init pattern as
+`getRedis()` in `redis.ts`): returns a query function or `null` if
+`DATABASE_URL` is not set.
 
 ```typescript
 import { getDb } from '~/server/utils/neon';
@@ -109,10 +99,37 @@ export default defineEventHandler(async () => {
 });
 ```
 
-The driver uses tagged template literals for automatic SQL injection
+The Neon driver uses tagged template literals for automatic SQL injection
 protection — `await sql\`SELECT * FROM notes WHERE id = ${id}\`` is safe.
 No ORM, no query builder, no connection pool setup needed.
 
+### If `server/utils/neon.ts` doesn't exist
+
+Create it manually (or re-run init):
+
+```bash
+npm install @neondatabase/serverless
+```
+
+```typescript
+// server/utils/neon.ts
+import { neon, type NeonQueryFunction } from '@neondatabase/serverless';
+
+let _sql: NeonQueryFunction | null = null;
+
+export function isDbConfigured(): boolean {
+  return Boolean(process.env.DATABASE_URL);
+}
+
+export function getDb(): NeonQueryFunction | null {
+  if (_sql) return _sql;
+  const url = process.env.DATABASE_URL;
+  if (!url) return null;
+  _sql = neon(url);
+  return _sql;
+}
+```
+
 ## Key Differences from Client-Side Code
 
 - Server routes run on the server (Node.js), not in the browser