@gallopsystems/agent-skills 1.19.0 → 1.20.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gallopsystems/agent-skills",
-  "version": "1.19.0",
+  "version": "1.20.1",
   "description": "Gallop Systems agent skills, symlinked into .claude/skills (Claude Code) and .agents/skills (Codex) on install.",
   "license": "UNLICENSED",
   "repository": {

package/plugins/kysely-postgres/skills/kysely-postgres/references/common-pitfalls.md

@@ -49,6 +49,39 @@ Rule of thumb: **convert when the raw SQL names a column or table; leave it when
 it is only parameters and literals.** The latter compiles to identical SQL and the
 "type-safe" rewrite verifies nothing.
 
+**One more trap in the canonical `count(*)` swap above: it returns a *string* at
+runtime, and a type parameter won't change that.** `eb.fn.countAll()` emits a bare
+`count(*)`, which PostgreSQL returns as `bigint` — and the `pg` driver deserializes
+`bigint` to a JavaScript **string** by default (see why below). So the row's `count`
+is `"2"`, not `2`:
+
+```typescript
+// MISLEADING - compiles, but lies about the runtime value
+.select((eb) => eb.fn.countAll<number>().as("count"))
+// `<number>` is a pure type assertion. The driver still hands back a string,
+// so `row.count === 2` is false and `row.count.toFixed()` throws.
+
+// RIGHT - cast in SQL so the driver parses a real number
+.select((eb) => eb.cast<number>(eb.fn.countAll(), "integer").as("count"))
+// emits `cast(count(*) as integer)` -> int4 -> the driver yields a JS number
+```
+
+The rule generalizes: **typing a `sql`/builder expression as `<number>` does not
+change the value the driver produces — only a SQL-level cast does.** Any
+`bigint`-returning aggregate (`count`, `sum` over a `bigint`, etc.) needs an explicit
+`cast` when downstream code expects a JS number.
+
+> **Why `bigint` comes back as a string — and don't "fix" it globally.** The `pg`
+> driver returns `int8`/`bigint` as a string on purpose: a JS `number` is a float64,
+> exact only to `2^53 - 1`, while `bigint` runs to `2^63 - 1`, so auto-parsing would
+> silently corrupt large IDs. You *can* register `pg.types.setTypeParser` to coerce
+> `int8` to a number, but it reintroduces that precision footgun for **every**
+> `bigint` column (primary keys included), and `kysely-codegen` has no
+> `--bigint-parser` flag (only `--date-parser` / `--numeric-parser`) — so the
+> generated `Int8` type still selects as `string` and you would be hand-overriding an
+> alias that regeneration clobbers. Keep the string default and `cast` per query where
+> you need a number.
+
 ### 2. Don't Forget .execute()
 
 Queries are lazy - they won't run without calling an execute method:

package/plugins/kysely-postgres/skills/kysely-postgres/references/json-jsonb-arrays.md

@@ -351,6 +351,37 @@ await db
   .execute();
 ```
 
+**`doUpdateSet` object vs callback form.** `doUpdateSet` takes either a plain
+object `doUpdateSet({ col: value })` or a callback `doUpdateSet((eb) => ({ ... }))`.
+The object form has no expression builder, so the moment you need a *builder
+expression* for any column — arithmetic, an `EXCLUDED` reference, a coalesce — you
+must switch the whole call to the callback form. Inside it, a **bare column name
+refers to the target (existing) row**, and **`eb.ref("excluded.<col>")` references
+the incoming row** (Kysely lowercases it to Postgres's `excluded` pseudo-table).
+The other columns come along unchanged inside the returned object:
+
+```typescript
+// Raw sql for the increment / EXCLUDED — column names are unchecked strings
+.onConflict((oc) =>
+  oc.column("email").doUpdateSet({
+    reply_count: sql`reply_count + 1`,
+    email: sql`EXCLUDED.email`,
+    status: "active",                       // plain value, fine in either form
+  }),
+)
+
+// Callback form unlocks eb(): both column refs are now type-checked
+.onConflict((oc) =>
+  oc.column("email").doUpdateSet((eb) => ({
+    reply_count: eb("reply_count", "+", 1),
+    email: eb.ref("excluded.email"),
+    status: "active",
+  })),
+)
+```
+
+The same object-vs-callback rule applies to `.set()` on a plain `UPDATE` (see below).
+
 ### UPDATE Operations
 
 ```typescript

package/plugins/kysely-postgres/skills/kysely-postgres/references/mutations.ts

@@ -43,11 +43,27 @@ const upsertedProduct = await db
     oc.column("sku").doUpdateSet((eb) => ({
       // Update these columns on conflict - type-safe!
       stock_quantity: eb("product.stock_quantity", "+", eb.ref("excluded.stock_quantity")),
+      // Prefer typed builders over raw sql here too: eb.fn.coalesce(...) over both
+      // tables validates names against the schema (excluded is a real virtual table)
+      name: eb.fn.coalesce(eb.ref("product.name"), eb.ref("excluded.name")),
     }))
   )
   .returning(["id", "sku", "stock_quantity"])
   .executeTakeFirst();
 
+// GOTCHA: when you DO need raw sql in a SET / doUpdateSet value (e.g. now()),
+// do NOT parameterize it with a codegen ColumnType marker like the generated
+// `Timestamp` (= ColumnType<Date, ...>). It breaks compilation:
+//   updated_at: sql<Timestamp>`now()`   // ❌ TS2345: RawBuilder<Timestamp> not
+//                                        //    assignable; "isSelectQueryBuilder" missing
+// The SET target is the flattened Updateable value type (e.g. string | Date | undefined),
+// and RawBuilder<ColumnType<...>> falls outside that plain-value branch. Use a plain
+// value type or leave it bare instead:
+//   updated_at: sql<Date>`now()`        // ✅ Date is a plain value type
+//   updated_at: sql`now()`              // ✅ also assigns cleanly
+// (The "always type your sql literals" rule is aimed at SELECT, where the type flows
+// into the result. In write contexts, ColumnType markers are the wrong parameter.)
+
 // OnConflict variations:
 // - oc.column("col") - single column constraint
 // - oc.columns(["col1", "col2"]) - composite constraint