@gallopsystems/agent-skills 1.18.0 → 1.20.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gallopsystems/agent-skills",
-  "version": "1.18.0",
+  "version": "1.20.0",
   "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:
@@ -159,3 +192,40 @@ The `"between"` operator looks like it should work but compiles to a tuple, whic
 .where((eb) => eb.betweenSymmetric("age", 65, 18))   // swaps bounds if needed
 ```
 
+### 9. Builder Argument Strings Are Column References, Not Literals
+
+This bites hardest when converting raw `sql` to builders. In `eb.fn.coalesce`,
+binary `eb(lhs, op, rhs)`, and most `eb.fn` calls, a bare string argument is
+interpreted as a **column reference**, not a string value. So porting
+`` sql`coalesce(status, 'pending')` `` naively produces a query that looks for a
+column named `pending`:
+
+```typescript
+// WRONG - 'pending' is read as a column name -> "column \"pending\" does not exist"
+eb.fn.coalesce("status", "pending")
+
+// RIGHT - wrap a literal default in eb.val() (parameterized) ...
+eb.fn.coalesce("status", eb.val("pending"))
+// ... or a typed sql`` literal when you need it inlined (e.g. inside GROUP BY)
+eb.fn.coalesce("status", sql<string>`'pending'`)
+
+// Number/boolean/null literals can use eb.lit (eb.lit rejects strings, see
+// expression-builder.md):
+eb.fn.coalesce("score", eb.lit(0))
+
+// Coalescing two real COLUMNS is the case where bare strings are correct:
+eb.fn.coalesce("preferred_name", "legal_name")   // both are column refs
+```
+
+A companion trap: when you feed a `sql`` fragment as the right-hand operand of a
+typed operator (e.g. a full-text `@@`), the fragment must carry a type parameter
+or it infers `unknown` and the operator overload rejects it:
+
+```typescript
+// WRONG - RawBuilder<unknown> is not a valid operand -> TS2345
+.where("search_vector", "@@", sql`to_tsquery('english', ${q})`)
+
+// RIGHT - type the fragment so it satisfies the operator's operand type
+.where("search_vector", "@@", sql<string>`to_tsquery('english', ${q})`)
+```
+

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