postgresdk 0.19.4 → 0.19.5

package/README.md

@@ -1063,12 +1063,13 @@ Commands:
   init                 Create a postgresdk.config.ts file
   generate             Generate SDK from database
   pull                 Pull SDK from API endpoint
+  install-skill        Install Claude Code skill for PostgreSDK
   version              Show version
   help                 Show help
 
 Options:
   -c, --config <path>  Path to config file (default: postgresdk.config.ts)
-  --force, -y          Delete stale files without prompting (generate & pull)
+  --force, -y          Delete stale files without prompting (generate & pull); overwrite existing skill (install-skill)
 
 Init subcommands/flags:
   init pull            Generate pull-only config (alias for --sdk)
@@ -1084,6 +1085,7 @@ Examples:
   npx postgresdk@latest generate --force                  # Skip stale file prompts
   npx postgresdk@latest pull --from=https://api.com --output=./src/sdk
   npx postgresdk@latest pull --from=https://api.com --output=./src/sdk --force
+  npx postgresdk@latest install-skill                      # Install Claude Code skill
 ```
 
 ### Generated Tests

package/dist/cli-install-skill.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Install the PostgreSDK Claude Code skill into the current project.
+ * Copies skills/postgresdk/SKILL.md → .claude/skills/postgresdk/SKILL.md
+ */
+export declare function installSkillCommand(args: string[]): Promise<void>;

package/dist/cli.js

@@ -2483,6 +2483,44 @@ var init_cli_pull = __esm(() => {
   init_cli_utils();
 });
 
+// src/cli-install-skill.ts
+var exports_cli_install_skill = {};
+__export(exports_cli_install_skill, {
+  installSkillCommand: () => installSkillCommand
+});
+import { readFileSync as readFileSync3, writeFileSync as writeFileSync2, mkdirSync, existsSync as existsSync5 } from "node:fs";
+import { join as join4, dirname as dirname4 } from "node:path";
+import { fileURLToPath as fileURLToPath2 } from "node:url";
+async function installSkillCommand(args) {
+  const force = parseForceFlag(args);
+  const destDir = join4(process.cwd(), ".claude", "skills", "postgresdk");
+  const destPath = join4(destDir, "SKILL.md");
+  if (existsSync5(destPath) && !force) {
+    console.log("⚠️  Skill already exists at .claude/skills/postgresdk/SKILL.md");
+    console.log("   Use --force to overwrite.");
+    return;
+  }
+  const srcPath = join4(__dirname3, "..", "skills", "postgresdk", "SKILL.md");
+  if (!existsSync5(srcPath)) {
+    console.error("❌ Could not find bundled skill file. This is a bug — please report it.");
+    process.exit(1);
+  }
+  const content = readFileSync3(srcPath, "utf-8");
+  mkdirSync(destDir, { recursive: true });
+  writeFileSync2(destPath, content, "utf-8");
+  console.log("✅ Installed PostgreSDK skill to .claude/skills/postgresdk/SKILL.md");
+  console.log("");
+  console.log("   Claude Code will now use this skill when you ask about your");
+  console.log("   generated API or SDK. Try asking it to help with queries,");
+  console.log("   filtering, includes, auth setup, or transactions.");
+}
+var __filename3, __dirname3;
+var init_cli_install_skill = __esm(() => {
+  init_cli_utils();
+  __filename3 = fileURLToPath2(import.meta.url);
+  __dirname3 = dirname4(__filename3);
+});
+
 // src/index.ts
 var import_config = __toESM(require_config(), 1);
 import { join as join2, relative, dirname as dirname2 } from "node:path";
@@ -8035,13 +8073,13 @@ async function generate(configPath, options) {
 // src/cli.ts
 var import_config2 = __toESM(require_config(), 1);
 import { resolve as resolve3 } from "node:path";
-import { readFileSync as readFileSync3 } from "node:fs";
-import { fileURLToPath as fileURLToPath2 } from "node:url";
-import { dirname as dirname4, join as join4 } from "node:path";
+import { readFileSync as readFileSync4 } from "node:fs";
+import { fileURLToPath as fileURLToPath3 } from "node:url";
+import { dirname as dirname5, join as join5 } from "node:path";
 init_cli_utils();
-var __filename3 = fileURLToPath2(import.meta.url);
-var __dirname3 = dirname4(__filename3);
-var packageJson = JSON.parse(readFileSync3(join4(__dirname3, "../package.json"), "utf-8"));
+var __filename4 = fileURLToPath3(import.meta.url);
+var __dirname4 = dirname5(__filename4);
+var packageJson = JSON.parse(readFileSync4(join5(__dirname4, "../package.json"), "utf-8"));
 var VERSION = packageJson.version;
 var args = process.argv.slice(2);
 var command = args[0];
@@ -8060,6 +8098,7 @@ Commands:
   init                 Create a postgresdk.config.ts file
   generate, gen        Generate SDK from database
   pull                 Pull SDK from API endpoint
+  install-skill        Install Claude Code skill for PostgreSDK
   version              Show version
   help                 Show help
 
@@ -8077,6 +8116,9 @@ Pull Options:
   --force, -y          Delete stale files without prompting
   -c, --config <path>  Path to config file with pull settings
 
+Install-skill Options:
+  --force, -y          Overwrite existing skill
+
 Examples:
   postgresdk init                        # Create config file
   postgresdk generate                    # Generate using postgresdk.config.ts
@@ -8084,6 +8126,7 @@ Examples:
   postgresdk generate -c custom.config.ts
   postgresdk pull --from=https://api.com --output=./src/sdk
   postgresdk pull                        # Pull using config file
+  postgresdk install-skill               # Install Claude Code skill
 `);
   process.exit(0);
 }
@@ -8106,6 +8149,9 @@ if (command === "init") {
 } else if (command === "pull") {
   const { pullCommand: pullCommand2 } = await Promise.resolve().then(() => (init_cli_pull(), exports_cli_pull));
   await pullCommand2(args.slice(1));
+} else if (command === "install-skill") {
+  const { installSkillCommand: installSkillCommand2 } = await Promise.resolve().then(() => (init_cli_install_skill(), exports_cli_install_skill));
+  await installSkillCommand2(args.slice(1));
 } else {
   console.error(`❌ Unknown command: ${command}`);
   console.error(`Run 'postgresdk help' for usage information`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "postgresdk",
-  "version": "0.19.4",
+  "version": "0.19.5",
   "description": "Generate a typed server/client SDK from a Postgres schema (includes, Zod, Hono).",
   "type": "module",
   "bin": {
@@ -14,6 +14,7 @@
   },
   "files": [
     "dist",
+    "skills",
     "README.md",
     "LICENSE"
   ],

package/skills/postgresdk/SKILL.md

@@ -0,0 +1,394 @@
+---
+name: postgresdk
+description: "How to use a PostgreSDK-generated API and client SDK. Use this skill whenever the user is working with code generated by PostgreSDK — including the typed client SDK (e.g., `sdk.users.list()`, `sdk.books.create()`), the generated Hono API server (router, routes, auth middleware), or the CONTRACT.md/contract.ts reference files. Trigger on: SDK method calls like `.list()`, `.getByPk()`, `.create()`, `.update()`, `.upsert()`, `.$transaction()`, `.listWith*()`, WHERE clause operators like `$ilike`, `$in`, `$gte`, `$jsonbContains`, mentions of `postgresdk`, `CONTRACT.md`, `createRouter`, `BaseClient`, `PaginatedResponse`, `InsertX`/`SelectX`/`UpdateX` types, `postgresdk.config.ts`, or any questions about filtering, includes, pagination, vector search, or trigram search in the context of a generated API."
+---
+
+# PostgreSDK Assistant
+
+You are helping a developer who is using code generated by [PostgreSDK](https://github.com/nickreese/postgresdk) — a tool that generates a fully typed Hono API server and TypeScript client SDK from a PostgreSQL database schema.
+
+## First: Discover the Generated Code
+
+The output directory is fully configurable via `postgresdk.config.ts` — don't assume paths like `./api/server` or `./api/client`. Discover where the generated code actually lives:
+
+1. **Search for `postgresdk.config.ts`** — if present, read the `outDir` value. It can be a string (e.g. `"./generated"`) or an object (`{ client: "./sdk", server: "./backend" }`). This tells you where the generated directories are.
+2. **Search for generated marker files** — if no config, glob for `**/router.ts`, `**/base-client.ts`, or `**/CONTRACT.md` and look for the `AUTO-GENERATED FILE` header to find the generated output directories.
+
+Once you've found the generated directories, identify which side the user is working on:
+
+**API-side** (runs the server):
+- Has a directory containing `router.ts`, `routes/*.ts`, `contract.ts`, `sdk-bundle.ts`
+- Has `postgresdk.config.ts` with `connectionString`
+- Asks about `createRouter`, `onRequest`, auth config, deployment, database drivers
+
+**SDK-side** (consumes the API):
+- Has a directory containing `base-client.ts`, table client files (e.g. `users.ts`), `CONTRACT.md`
+- May have `postgresdk.config.ts` with a `pull` section instead of `connectionString`
+- Asks about `sdk.tableName.method()`, filtering, includes, transactions
+
+**Both** — common when a single `outDir` generates server and client subdirectories.
+
+## Second: Read the Contract
+
+The generated `CONTRACT.md` is the single source of truth for the user's specific schema. It contains every table, field, type, method, endpoint, and relationship. Read it before answering schema-specific questions.
+
+Search with `**/CONTRACT.md` and look for the one with the `AUTO-GENERATED` header. It exists in both the server and client output directories — either copy works, they're identical.
+
+If you can't find it, ask the user where their generated code lives.
+
+## SDK Reference
+
+### Initialization
+
+```typescript
+// Import path depends on outDir config — find the generated client directory
+import { SDK } from '<client-dir>';
+
+const sdk = new SDK({
+  baseUrl: 'http://localhost:3000',
+  auth: {
+    apiKey: 'your-key',           // API key auth
+    // OR
+    jwt: 'your-token',           // Static JWT
+    // OR
+    jwt: async () => getToken(), // Async JWT provider
+  }
+});
+```
+
+### CRUD Operations
+
+Every table gets these methods (assuming single primary key):
+
+```typescript
+// Create
+const item = await sdk.users.create({ name: 'Alice', email: 'alice@example.com' });
+
+// Read
+const user = await sdk.users.getByPk('id-123');           // single record or null
+const result = await sdk.users.list({ limit: 20 });       // paginated
+
+// Update
+const updated = await sdk.users.update('id-123', { name: 'Bob' });
+
+// Upsert (insert or update on conflict)
+const upserted = await sdk.users.upsert({
+  where:  { email: 'alice@example.com' },       // unique constraint columns
+  create: { email: 'alice@example.com', name: 'Alice' },
+  update: { name: 'Alice Updated' },
+});
+
+// Delete
+await sdk.users.hardDelete('id-123');   // permanent
+await sdk.users.softDelete('id-123');   // sets soft-delete column (if configured)
+```
+
+### Paginated Response Shape
+
+All `list()` calls return:
+```typescript
+{
+  data: T[];          // array of records
+  total: number;      // total matching records (respects WHERE)
+  limit?: number;     // page size (absent when no limit)
+  offset: number;     // current offset
+  hasMore: boolean;   // more pages available
+}
+```
+
+### WHERE Filtering
+
+Root-level keys are AND'd. Use `$or`/`$and` for logic (2 nesting levels max).
+
+```typescript
+await sdk.users.list({
+  where: {
+    age: { $gte: 18, $lt: 65 },
+    email: { $ilike: '%@company.com' },
+    status: { $in: ['active', 'pending'] },
+    deleted_at: { $is: null },
+    $or: [{ role: 'admin' }, { role: 'mod' }]
+  }
+});
+```
+
+**Available operators:**
+
+| Operator | SQL | Applies to |
+|----------|-----|------------|
+| `$eq`, `$ne` | `=`, `!=` | All types |
+| `$gt`, `$gte`, `$lt`, `$lte` | `>`, `>=`, `<`, `<=` | Number, Date |
+| `$in`, `$nin` | `IN`, `NOT IN` | All types |
+| `$like`, `$ilike` | `LIKE`, `ILIKE` | Strings |
+| `$is`, `$isNot` | `IS NULL`, `IS NOT NULL` | Nullable fields |
+| `$similarity`, `$wordSimilarity`, `$strictWordSimilarity` | pg_trgm operators | Strings (requires pg_trgm) |
+| `$jsonbContains` | `@>` | JSONB |
+| `$jsonbContainedBy` | `<@` | JSONB |
+| `$jsonbHasKey` | `?` | JSONB |
+| `$jsonbHasAnyKeys` | `?\|` | JSONB |
+| `$jsonbHasAllKeys` | `?&` | JSONB |
+| `$jsonbPath` | Path-based query | JSONB |
+| `$or`, `$and` | `OR`, `AND` | Logical combinators |
+
+### Sorting
+
+```typescript
+// Single column
+await sdk.users.list({ orderBy: 'created_at', order: 'desc' });
+
+// Multi-column with per-column direction
+await sdk.users.list({
+  orderBy: ['status', 'created_at'],
+  order: ['asc', 'desc']
+});
+```
+
+### DISTINCT ON
+
+```typescript
+const latestPerUser = await sdk.events.list({
+  distinctOn: 'user_id',
+  orderBy: 'created_at',
+  order: 'desc'
+});
+```
+
+### Field Selection
+
+```typescript
+// Only return specific fields
+await sdk.users.list({ select: ['id', 'email', 'name'] });
+
+// Return all fields except these
+await sdk.users.list({ exclude: ['password_hash', 'secret_token'] });
+
+// Works on single-record operations too
+await sdk.users.create(data, { select: ['id', 'email'] });
+await sdk.users.update(id, patch, { exclude: ['updated_at'] });
+await sdk.users.getByPk(id, { select: ['id', 'name'] });
+```
+
+### Relationships & Includes
+
+**Generic include:**
+```typescript
+const result = await sdk.authors.list({
+  include: { books: true }
+});
+// result.data[0].books is SelectBooks[]
+```
+
+**Typed convenience methods** (generated per-table based on relationships):
+```typescript
+// listWith* and getByPkWith* — check CONTRACT.md for what's available
+const result = await sdk.authors.listWithBooks({ limit: 10 });
+const author = await sdk.authors.getByPkWithBooksAndTags('id');
+
+// Control included relations
+await sdk.authors.listWithBooks({
+  booksInclude: { orderBy: 'published_at', order: 'desc', limit: 5 }
+});
+```
+
+**Nested includes:**
+```typescript
+const result = await sdk.authors.list({
+  include: { books: { tags: true } }
+});
+// result.data[0].books[0].tags is SelectTags[]
+```
+
+**Select/exclude on includes:**
+```typescript
+await sdk.authors.list({
+  select: ['id', 'name'],
+  include: {
+    books: { select: ['id', 'title'], orderBy: 'published_at', limit: 5 }
+  }
+});
+```
+
+### Atomic Transactions
+
+Use `$`-prefixed lazy builders inside `$transaction`:
+
+```typescript
+const [order, updatedUser] = await sdk.$transaction([
+  sdk.orders.$create({ user_id: user.id, total: 99 }),
+  sdk.users.$update(user.id, { last_order_at: new Date().toISOString() }),
+]);
+// TypeScript infers: [SelectOrders, SelectUsers | null]
+```
+
+Available builders: `$create`, `$update`, `$softDelete`, `$hardDelete`, `$upsert`.
+
+All operations are Zod-validated before `BEGIN`. On failure, the entire transaction rolls back and throws with a `.failedAt` index.
+
+### Soft Deletes
+
+When `softDeleteColumn` is configured in `postgresdk.config.ts`:
+- `softDelete(id)` — sets the column (e.g. `deleted_at = NOW()`)
+- `hardDelete(id)` — permanent `DELETE` (unless `exposeHardDelete: false`)
+- Soft-deleted rows are hidden from `list`/`getByPk` by default
+- Pass `includeSoftDeleted: true` to see them
+
+### Vector Search (pgvector)
+
+For tables with `vector` columns. Results auto-include `_distance`.
+
+```typescript
+const results = await sdk.video_sections.list({
+  vector: {
+    field: 'vision_embedding',
+    query: embeddingArray,         // number[]
+    metric: 'cosine',             // 'cosine' | 'l2' | 'inner'
+    maxDistance: 0.5               // optional threshold
+  },
+  where: { status: 'published' }, // combine with regular filters
+  limit: 10
+});
+// results.data[0]._distance
+```
+
+### Trigram Search (pg_trgm)
+
+Fuzzy text search. Results auto-include `_similarity`.
+
+```typescript
+const results = await sdk.books.list({
+  trigram: {
+    field: 'title',
+    query: 'postgrs',            // typo-tolerant
+    metric: 'similarity',        // 'similarity' | 'wordSimilarity' | 'strictWordSimilarity'
+    threshold: 0.3               // min score 0–1
+  },
+  limit: 10
+});
+```
+
+**Multi-field:** `fields: ['name', 'url']` with `strategy: 'greatest' | 'concat'`, or weighted: `fields: [{ field: 'name', weight: 2 }, { field: 'url', weight: 1 }]`.
+
+Note: `trigram` and `vector` are mutually exclusive on a single `list()` call.
+
+### Type Imports
+
+Import paths below use `<client>` as a placeholder — substitute the actual path to the generated client directory (determined by the `outDir` config).
+
+```typescript
+import { SDK } from '<client>';
+import type { SelectUsers, InsertUsers, UpdateUsers } from '<client>/types/users';
+import type { PaginatedResponse } from '<client>/types/shared';
+
+// Zod schemas (for form validation, etc.)
+import { InsertUsersSchema, UpdateUsersSchema } from '<client>/zod/users';
+
+// Params schemas
+import { UsersListParamsSchema, UsersPkSchema } from '<client>/params/users';
+```
+
+## API Server Reference
+
+### Basic Setup
+
+```typescript
+import { Hono } from 'hono';
+import { serve } from '@hono/node-server';
+import { Client } from 'pg';
+import { createRouter } from '<server>/router'; // path depends on outDir config
+
+const app = new Hono();
+const pg = new Client({ connectionString: process.env.DATABASE_URL });
+await pg.connect();
+
+const apiRouter = createRouter({ pg });
+app.route('/', apiRouter);
+
+serve({ fetch: app.fetch, port: 3000 });
+```
+
+### Auth Configuration (in postgresdk.config.ts)
+
+```typescript
+export default {
+  connectionString: process.env.DATABASE_URL,
+  auth: {
+    // Option A: API key
+    apiKey: process.env.API_KEY,
+
+    // Option B: JWT (supports multiple services)
+    jwt: {
+      services: [
+        { issuer: 'web-app', secret: 'env:WEB_SECRET' },
+        { issuer: 'mobile', secret: 'env:MOBILE_SECRET' },
+      ],
+      audience: 'my-api'   // optional
+    }
+  }
+};
+```
+
+### onRequest Hook
+
+Runs before every endpoint. Use for RLS, audit logging, authorization:
+
+```typescript
+const apiRouter = createRouter({
+  pg,
+  onRequest: async (c, pg) => {
+    const auth = c.get('auth');
+
+    // Set PostgreSQL session variable for RLS
+    if (auth?.kind === 'jwt' && auth.claims?.sub) {
+      await pg.query(`SET LOCAL app.user_id = '${auth.claims.sub}'`);
+    }
+
+    // Scope-based authorization
+    const scopes = auth?.claims?.scopes || [];
+    const table = c.req.path.split('/')[2];
+    if (!hasPermission(scopes, table, c.req.method)) {
+      throw new Error('Forbidden');
+    }
+  }
+});
+```
+
+### Deployment Patterns
+
+- **Serverless** (Vercel, Cloudflare): Use `Pool` with `max: 1` — each instance is ephemeral
+- **Traditional** (Railway, VPS): Use `Pool` with `max: 10` — reuse connections across requests
+- **Edge**: Use `@neondatabase/serverless` Pool, set `useJsExtensions: true` in config
+
+### SDK Distribution
+
+The generated server auto-serves the client SDK:
+- `GET /_psdk/sdk/manifest` — file listing
+- `GET /_psdk/sdk/download` — complete bundle
+- `GET /_psdk/contract.md` — markdown contract
+- `GET /_psdk/contract.json` — JSON contract
+
+Clients pull with: `npx postgresdk@latest pull --from=https://api.example.com --output=./src/sdk`
+
+Protect with `pullToken` in config if needed.
+
+## Key Configuration Options
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `schema` | `"public"` | Database schema to introspect |
+| `outDir` | `"./api"` | Output dir (or `{ client, server }`) |
+| `numericMode` | `"auto"` | `"auto"` / `"number"` / `"string"` |
+| `maxLimit` | `1000` | Max allowed `limit` (0 = no cap) |
+| `includeMethodsDepth` | `2` | Max depth for `listWith*` methods |
+| `dateType` | `"date"` | `"date"` / `"string"` |
+| `useJsExtensions` | `false` | Add `.js` to imports (Edge/Deno) |
+| `delete.softDeleteColumn` | — | Column name for soft deletes |
+| `delete.exposeHardDelete` | `true` | Also expose `hardDelete()` |
+
+## Common Gotchas
+
+- **list() uses POST** — the `list` method sends a POST to `/v1/{table}/list` (not GET) because complex WHERE/include payloads don't fit in query strings. The simple GET endpoint exists too but only supports basic query params.
+- **Composite PKs** — tables with composite primary keys don't get `getByPk`, `update`, `delete`, or `upsert` methods. Use `list` with WHERE filters instead.
+- **Junction tables** — M:N junction tables (like `book_tags`) are detected automatically. The SDK generates include methods that skip the junction table: `sdk.books.listWithTags()` gives you tags directly, not book_tags.
+- **Import paths** — depend entirely on the `outDir` config in `postgresdk.config.ts`. Always discover the actual generated directory before suggesting imports.
+- **Types naming** — `Select{PascalTable}`, `Insert{PascalTable}`, `Update{PascalTable}` (e.g., `SelectUsers`, `InsertUsers`).
+- **Regeneration** — all generated files have `AUTO-GENERATED FILE - DO NOT EDIT` headers. Changes are overwritten on `generate` or `pull`. Extend behavior via `onRequest` hooks, not by editing generated code.