@gallopsystems/agent-skills 1.17.0 → 1.19.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gallopsystems/agent-skills",
-  "version": "1.17.0",
+  "version": "1.19.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

@@ -20,6 +20,35 @@
 )
 ```
 
+**…but only when the expression references the schema.** The whole payoff of
+dropping raw `sql` is letting Kysely validate column/table names against your
+generated types — so the value is proportional to how many schema identifiers the
+expression names. A `sql` template made only of **bound parameters and constants**
+has nothing to check; converting it is lateral churn, and occasionally worse:
+
+```typescript
+// WORTH CONVERTING - names a column, so eb.ref/eb() validate it exists
+.where(sql`lower(name)`, "=", value)
+.where((eb) => eb(eb.fn<string>("lower", [eb.ref("name")]), "=", value))
+
+// WORTH CONVERTING - correlated EXISTS validates table + both column refs
+sql<boolean>`EXISTS (SELECT 1 FROM child WHERE child.parent_id = parent.id)`
+eb.exists(eb.selectFrom("child").select(eb.lit(1).as("one"))
+  .whereRef("child.parent_id", "=", "parent.id"))
+
+// LEAVE RAW - a bound param + a constant cast: no column, nothing to verify.
+// The "typed" form is also a schema MISMATCH: eb.cast(...) is Expression<Date>,
+// but a DATE column is codegen'd as `string` (with --date-parser string).
+sql`${value}::date`            // keep it
+
+// LEAVE RAW - bare string/number/bool literals have no schema surface
+sql.lit("Unassigned")          // keep it (or eb.lit for number/bool, but no real gain)
+```
+
+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.
+
 ### 2. Don't Forget .execute()
 
 Queries are lazy - they won't run without calling an execute method:
@@ -130,3 +159,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})`)
+```
+