@gallopsystems/agent-skills 1.14.0 → 1.16.0

package/plugins/kysely-postgres/skills/kysely-postgres/references/query-patterns.md

@@ -0,0 +1,235 @@
+## Query Patterns
+
+### Basic SELECT
+
+```typescript
+// Select all columns
+const users = await db.selectFrom("user").selectAll().execute();
+
+// Select specific columns with aliases
+const users = await db
+  .selectFrom("user")
+  .select(["id", "email", "first_name as firstName"])
+  .execute();
+
+// Single row (returns T | undefined)
+const user = await db.selectFrom("user").selectAll()
+  .where("id", "=", userId).executeTakeFirst();
+
+// Single row that must exist (throws if not found)
+const user = await db.selectFrom("user").selectAll()
+  .where("id", "=", userId).executeTakeFirstOrThrow();
+```
+
+### WHERE Clauses
+
+```typescript
+// Equality, comparison, IN, LIKE
+.where("status", "=", "active")
+.where("price", ">", 100)
+.where("role", "in", ["admin", "manager"])
+.where("name", "like", "%search%")
+.where("deleted_at", "is", null)
+
+// BETWEEN - use eb.between(), NOT the "between" operator (see Pitfall #8)
+.where((eb) => eb.between("age", 18, 65))
+
+// Multiple conditions (chained = AND)
+.where("is_active", "=", true)
+.where("role", "=", "admin")
+
+// OR conditions
+.where((eb) => eb.or([
+  eb("role", "=", "admin"),
+  eb("role", "=", "manager"),
+]))
+
+// Complex AND/OR
+.where((eb) => eb.and([
+  eb("is_active", "=", true),
+  eb.or([
+    eb("price", "<", 50),
+    eb("stock", ">", 100),
+  ]),
+]))
+```
+
+### JOINs
+
+```typescript
+// Inner join
+.innerJoin("order", "order.user_id", "user.id")
+
+// Left join
+.leftJoin("category", "category.id", "product.category_id")
+
+// Self-join with alias
+.selectFrom("category as c")
+.leftJoin("category as parent", "parent.id", "c.parent_id")
+
+// Multiple joins
+.innerJoin("order", "order.id", "order_item.order_id")
+.innerJoin("product", "product.id", "order_item.product_id")
+.innerJoin("user", "user.id", "order.user_id")
+```
+
+### Complex JOINs (Callback Format)
+
+Use the callback format when you need:
+- Multiple join conditions (composite keys)
+- Mixed column-to-column and column-to-literal comparisons
+- OR conditions within joins
+- Subquery joins (derived tables)
+
+**Join Builder Methods:**
+- `onRef(col1, op, col2)` - Column-to-column comparison
+- `on(col, op, value)` - Column-to-literal comparison
+- `on((eb) => ...)` - Complex expressions with OR logic
+
+```typescript
+// Multi-condition join (composite key + filter)
+.leftJoin("invoice as i", (join) =>
+  join
+    .onRef("sp.service_provider_id", "=", "i.service_provider_id")
+    .onRef("sp.year", "=", "i.year")
+    .onRef("sp.month", "=", "i.month")
+    .on("i.status", "!=", "invalidated")
+)
+
+// Join with OR conditions
+.leftJoin("order as o", (join) =>
+  join
+    .onRef("o.user_id", "=", "u.id")
+    .on((eb) =>
+      eb.or([
+        eb("o.status", "=", "completed"),
+        eb("o.status", "=", "shipped"),
+      ])
+    )
+)
+
+// Subquery join (derived table) - two callbacks
+.leftJoin(
+  (eb) =>
+    eb
+      .selectFrom("order")
+      .select((eb) => [
+        "user_id",
+        eb.fn.count("id").as("order_count"),
+        eb.fn.max("created_at").as("last_order_at"),
+      ])
+      .groupBy("user_id")
+      .as("order_stats"),  // MUST have alias!
+  (join) => join.onRef("order_stats.user_id", "=", "u.id")
+)
+
+// Cross join (always-true condition) - for joining aggregated CTEs
+.leftJoin("summary_cte", (join) =>
+  join.on(sql`true`, "=", sql`true`)
+)
+```
+
+### Aggregations
+
+```typescript
+.select((eb) => [
+  "status",
+  eb.fn.count("id").as("count"),
+  eb.fn.sum("total_amount").as("totalAmount"),
+  eb.fn.avg("total_amount").as("avgAmount"),
+])
+.groupBy("status")
+.having((eb) => eb.fn.count("id"), ">", 5)
+```
+
+#### FILTER (WHERE ...) on Aggregates
+
+PostgreSQL's `FILTER (WHERE ...)` clause is available on **all** aggregate function builders via `.filterWhere()`:
+
+```typescript
+.select((eb) => [
+  eb.fn.count("id").filterWhere("status", "=", "active").as("active_count"),
+  eb.fn.countAll().filterWhere("role", "!=", "banned").as("non_banned"),
+  eb.fn.sum("amount").filterWhere("type", "=", "credit").as("total_credits"),
+])
+
+// Also works as the first argument to .having()
+.having(
+  (eb) => eb.fn.countAll().filterWhere("status", "!=", "signed"),
+  "=",
+  0
+)
+```
+
+### ORDER BY
+
+```typescript
+// Simple ordering
+.orderBy("created_at", "desc")
+.orderBy("name", "asc")
+
+// NULLS FIRST / NULLS LAST - use order builder callback
+.orderBy("category_id", (ob) => ob.asc().nullsLast())
+.orderBy("priority", (ob) => ob.desc().nullsFirst())
+
+// Multiple columns - chain orderBy calls (array syntax is deprecated)
+.orderBy("category_id", "asc")
+.orderBy("price", "desc")
+.orderBy("name", "asc")
+```
+
+### CTEs (Common Table Expressions)
+
+Use CTEs for complex queries with multiple aggregation levels:
+
+```typescript
+const result = await db
+  .with("order_totals", (db) =>
+    db.selectFrom("order")
+      .innerJoin("user", "user.id", "order.user_id")
+      .select((eb) => [
+        "user.id as userId",
+        "user.email",
+        eb.fn.sum("order.total_amount").as("totalSpent"),
+        eb.fn.count("order.id").as("orderCount"),
+      ])
+      .groupBy(["user.id", "user.email"])
+  )
+  .selectFrom("order_totals")
+  .selectAll()
+  .orderBy("totalSpent", "desc")
+  .execute();
+```
+
+### JSON Aggregation (PostgreSQL)
+
+```typescript
+import { jsonBuildObject } from "kysely/helpers/postgres";
+// Note: jsonAgg is accessed via eb.fn.jsonAgg(), not imported
+
+.with("tasks", (db) =>
+  db.selectFrom("task")
+    .leftJoin("user", "user.id", "task.assignee_id")
+    .select((eb) => [
+      "task.job_id",
+      eb.fn.jsonAgg(
+        jsonBuildObject({
+          id: eb.ref("task.id"),
+          status: eb.ref("task.status"),
+          assignee: jsonBuildObject({
+            id: eb.ref("user.id"),
+            name: eb.fn<string>("concat", [
+              eb.ref("user.first_name"),
+              eb.cast(eb.val(" "), "text"),
+              eb.ref("user.last_name"),
+            ]),
+          }),
+        })
+      )
+      .filterWhere("task.id", "is not", null) // Filter nulls from left join
+      .as("tasks"),
+    ])
+    .groupBy("task.job_id")
+)
+```
+

package/plugins/kysely-postgres/skills/kysely-postgres/references/seeding-pattern.md

@@ -0,0 +1,143 @@
+# Idempotent seeding pattern
+
+How to seed a preview/dev database so it stays useful as the app grows — without
+the seeds drifting out of sync with the schema. This is a *convention*, not a
+Kysely feature; it layers on top of `kysely seed make` / `kysely seed run`.
+
+Not every project has (or needs) a seed system. Reach for this when there's a
+preview or dev box that a human logs into to *see* the app — a seedless box shows
+empty screens, so every new feature has to be seeded to be visible there. A
+library or a pure-API service with no such box doesn't need any of this.
+
+## What seeds are for (and what they are not)
+
+- **Migrations** define the schema. **Tests** assert behavior and roll back.
+  **Seeds** populate a *live* preview/dev DB with the minimum data needed to log
+  in and exercise the features — and they *commit*.
+- A seed's job is to make a feature **visible and reachable** in the preview, not
+  to test it. Seed one row per state worth seeing, not exhaustive permutations.
+
+## The core idea: factories shared by tests AND seeds
+
+Put the row-level builders in one framework-agnostic module (e.g.
+`db/factories.ts`) that both the test suite and the seeds import. Each builder
+inserts a single row with sensible defaults plus the FK ids the caller threads
+in.
+
+```ts
+// Accepts either a live connection (seeds) or a test transaction (tests).
+export type DbLike = Kysely<DB> | Transaction<DB>;
+
+export function createFactories(db: DbLike) {
+  return {
+    async user(data: Partial<{ email: string; name: string }> = {}) {
+      const n = nextSeq();
+      return db.insertInto("users")
+        .values({ email: data.email ?? `user${n}@example.com`, name: data.name ?? "User" })
+        .returningAll().executeTakeFirstOrThrow();
+    },
+    // ...one builder per table you seed
+  };
+}
+```
+
+- **Tests** call `createFactories(trx)` with a per-test transaction (rolled back).
+- **Seeds** call `createFactories(db)` with the live connection (committed).
+- A scene that reads well in a seed reads well in a test, and vice versa — one
+  source of truth for "a valid row of X".
+
+**DO** keep this module free of any test-framework import. Seeds load it at
+runtime under the bare `seed run` context (no test runner, no app DI / framework
+auto-imports), so a stray `import { test } from "vitest"` breaks `seed run`.
+
+## Uniqueness: a monotonic counter, not randomness
+
+Drive unique fields off a process-global counter, not random suffixes.
+
+```ts
+let seq = 0;
+const nextSeq = () => ++seq;   // user1@…, user2@…, never collides
+```
+
+- **DO** use `nextSeq()` for every "just needs to be unique" value.
+- **DON'T** use `Math.random()` / timestamps for uniqueness — they birthday-collide
+  eventually and make failures non-reproducible.
+
+## Idempotent + order-independent — the hard contract
+
+Seed runners (e.g. kysely-ctl) execute every file in directory-read order with
+**no ledger** and re-run on every preview deploy. So:
+
+- **Order-independent** — a seed must NOT depend on another seed having run
+  first. Each file builds the world it needs from factories.
+- **Idempotent** — running the full set twice must not throw and must not
+  duplicate. For most rows, `nextSeq()` already guarantees no collision. For a
+  row that must be **stable and addressable across re-seeds** (the canonical
+  example: the anchor login user the preview logs in as), upsert on a natural
+  key instead:
+
+```ts
+await db.insertInto("users").values(anchor)
+  .onConflict((oc) => oc.column("email").doUpdateSet(anchor))
+  .execute();
+```
+
+- **DON'T** hardcode a unique literal in a plain `insertInto` — the second run
+  throws on the unique constraint.
+- **DON'T** reach across files for an id; if two scenes truly share an entity,
+  give each its own copy or upsert a shared anchor both can look up by key.
+
+## Build scenes directly in their target state
+
+When an entity has a lifecycle (draft → sent → accepted), create each seed row
+*directly* in the state you want to see by writing the same stored columns the
+real transition writes (status + last-action + timestamps), rather than inserting
+a draft and calling the app's transition code.
+
+- **DO** set the columns directly. Seeds run in a bare context and should compose
+  only factories + plain inserts.
+- **DON'T** import the app's service/transition utilities into a seed — they
+  often rely on framework auto-imports or request context that doesn't exist
+  under `seed run`. (Guard the "directly-built state is actually reachable/
+  consistent" claim with a test instead.)
+
+## The validity harness — what keeps seeds from rotting
+
+Typecheck + codegen catch *shape* drift (a seed referencing a renamed column).
+They do **not** catch runtime breakage. Add one test — the validity harness —
+that, against a freshly-migrated schema:
+
+1. Runs **every** seed file (auto-discovered, so a new broken seed is caught for
+   free), inside a rolled-back transaction so the shared test DB stays clean.
+2. Runs the full set **twice** and asserts no throw — proving idempotency.
+
+This catches the two failure modes typecheck can't:
+
+- **Constraint drift** — a migration adds a NOT NULL column with no default, a
+  new CHECK, or a new UNIQUE, and every seed inserting that table now throws at
+  runtime while still typechecking.
+- **Non-idempotency** — a hardcoded unique value or an unhandled conflict that
+  only surfaces on the second run.
+
+**DO** discover seed files dynamically (glob / import-all) so the harness covers
+new seeds automatically. **DON'T** maintain a hand-listed array of seeds to test
+— it silently misses the next one added.
+
+## Preview login, briefly
+
+A preview box often serves on a dynamic URL that can't be a fixed OAuth redirect,
+so it logs in via a dev-only backdoor as the seeded anchor user. Keep the anchor
+user definition in **one** module that both the seed and the login route import,
+and gate the backdoor on **both** a compile-time dev check (dead in prod builds)
+**and** a runtime flag — so it can't ship enabled. The anchor user is the
+upsert-on-natural-key row from the idempotency section.
+
+## Checklist
+
+- [ ] Factories module is test-framework-free and shared by tests + seeds.
+- [ ] Unique values come from a counter, not randomness.
+- [ ] Each seed is self-sufficient (no cross-file ordering dependency).
+- [ ] Stable/addressable rows upsert on a natural key; everything else rides the counter.
+- [ ] Lifecycle rows are built directly in their target state, no app-util imports.
+- [ ] A validity harness runs every seed twice against the latest migration.
+- [ ] The preview anchor user lives in one module, gated dev-only + runtime-flagged.

package/plugins/kysely-postgres/skills/kysely-postgres/references/set-lateral-locking.md

@@ -0,0 +1,46 @@
+## Set Operations (UNION / INTERSECT / EXCEPT)
+
+Combine two compatible queries. Plain forms dedupe; `*All` forms keep duplicates (and are cheaper). See [set-operations.ts](references/set-operations.ts).
+
+```typescript
+db.selectFrom("order").select("user_id")
+  .except(db.selectFrom("review").select("user_id"))   // orders, never reviewed
+  .execute();
+// .union/.unionAll, .intersect/.intersectAll, .except/.exceptAll
+// Both branches must select matching columns/names — align with `as` aliases.
+```
+
+## LATERAL Joins (PostgreSQL)
+
+A `LATERAL` subquery can reference earlier tables via `whereRef` and runs per outer row — the best tool for **top-N-per-group with a per-row LIMIT**. Use `*Lateral` + `join.onTrue()`. See [joins.ts](references/joins.ts).
+
+```typescript
+// Each user's 3 most recent orders
+db.selectFrom("user as u")
+  .innerJoinLateral(
+    (eb) => eb.selectFrom("order as o")
+      .select(["o.id", "o.total_amount", "o.created_at"])
+      .whereRef("o.user_id", "=", "u.id")
+      .orderBy("o.created_at", "desc").limit(3).as("recent"),
+    (join) => join.onTrue()
+  )
+  .select(["u.email", "recent.id", "recent.total_amount"])
+  .execute();
+// leftJoinLateral / crossJoinLateral also exist.
+```
+
+## Row Locking (FOR UPDATE / SKIP LOCKED)
+
+Pessimistic locks for read-modify-write and job queues (run inside a transaction). See [locking.ts](references/locking.ts).
+
+```typescript
+// Job-queue worker: grab the next pending jobs, skipping rows other workers hold
+db.selectFrom("job").selectAll()
+  .where("status", "=", "pending")
+  .orderBy("created_at").limit(10)
+  .forUpdate().skipLocked()
+  .execute();
+// Lock strength: forKeyShare < forShare < forNoKeyUpdate < forUpdate
+// Wait behavior: .skipLocked() (skip) or .noWait() (error instead of blocking)
+```
+

package/plugins/kysely-postgres/skills/kysely-postgres/references/window-functions.md

@@ -0,0 +1,37 @@
+## Window Functions
+
+Two builders cover almost everything. See [window-functions.ts](references/window-functions.ts) for the full set.
+
+```typescript
+// Named window functions (no dedicated helper): eb.fn.agg<T>("NAME", [args])
+.select((eb) => [
+  eb.fn.agg<number>("ROW_NUMBER")
+    .over((ob) => ob.partitionBy("category_id").orderBy("price", "desc"))
+    .as("rank"),
+  // LAG/LEAD args go in the array; wrap literals in sql.lit()
+  eb.fn.agg<number | null>("LAG", ["total_amount", sql.lit(1)])
+    .over((ob) => ob.partitionBy("user_id").orderBy("created_at"))
+    .as("prev_amount"),
+])
+
+// Windowed aggregates: .over() on sum/count/avg/min/max
+.select((eb) => [
+  eb.fn.sum<number>("total_amount").over((ob) => ob.orderBy("created_at")).as("running_total"),
+  eb.fn.avg<number>("price").over().as("grand_avg"),               // empty OVER ()
+  // .filterWhere() and .distinct() compose with .over()
+  eb.fn.countAll<number>().filterWhere("status", "=", "completed")
+    .over((ob) => ob.partitionBy("user_id")).as("completed_for_user"),
+])
+```
+
+**Filtering on a window result** (e.g. `row_number = 1`) needs a CTE/subquery — windows are computed after `WHERE`, so rank in a CTE then filter the outer query.
+
+**Window frames (`ROWS`/`RANGE BETWEEN`) require raw SQL.** Kysely's `OverBuilder` exposes only `partitionBy`/`orderBy` — there is no frame node in its AST at all (true through 0.28, 0.29, and `main`), and `.over()` rejects a raw `sql` argument. Frame support is the open feature request [kysely-org/kysely#505](https://github.com/kysely-org/kysely/issues/505). Write the frame as raw SQL but keep column refs typed via `eb.ref()`:
+
+```typescript
+// Only the function name + frame keywords are raw; columns stay validated.
+sql<number>`avg(${eb.ref("total_amount")}) over (
+  order by ${eb.ref("created_at")} rows between 2 preceding and current row
+)`.as("moving_avg_3")
+```
+