@warlock.js/cascade 5.19.0 → 5.20.0

package/skills/run-cascade-cli/SKILL.md

@@ -1,125 +1,125 @@
----
-name: run-cascade-cli
-description: "Run the cascade CLI / Operations API in @warlock.js/cascade; use when you need to run cascade cli."
----
-
-# Run the cascade CLI / Operations API
-
-Cascade ships a standalone `cascade` binary plus a programmatic **Operations API** — named functions over the migration-runner singleton. The binary is a thin wrapper over those functions; warlock-core's CLI wraps the same code path. Use the binary from terminal / deploy scripts; use the Operations API from test setup, container init, or custom tooling.
-
-## CLI commands
-
-The standalone binary exposes four colon-keyed subcommands:
-
-```bash
-cascade migrate                 # run all pending migrations
-cascade migrate:list            # show executed migrations from _migrations
-cascade migrate:rollback        # undo the last batch
-cascade migrate:export-sql      # write .up.sql / .down.sql instead of executing
-```
-
-Flags:
-- `migrate` — `-f/--fresh` (drop everything and re-run), `-s/--sql` (export SQL instead of executing), `--pending-only`, `-c/--compact`, `-p/--path <glob>`
-- `migrate:rollback` — `-a/--all` (roll back everything), `--batches N`, `-p/--path <glob>`
-- `migrate:export-sql` — `--pending-only`, `-c/--compact`, `-p/--path <glob>`
-
-There is **no** `seed`, `db:create`, or `db:drop-tables` in the standalone binary — those need project context; use the warlock CLI when you have a Warlock app.
-
-## Configuration — env vars only
-
-No `cascade.config.{ts,js}` file. The CLI auto-loads `.env` from cwd at start.
-
-```bash
-DATABASE_URL=postgres://user:pass@host:5432/db    # one connection string …
-# … or discrete vars:
-DB_DIALECT=postgres        # or mongodb
-DB_HOST=localhost
-DB_PORT=5432
-DB_NAME=myapp
-DB_USER=postgres
-DB_PASSWORD=secret
-
-# Migration defaults — only set when overriding library defaults:
-CASCADE_PRIMARY_KEY=uuid   # uuid | int | bigInt
-CASCADE_UUID_STRATEGY=v7   # v4 | v7
-```
-
-Warlock-project aliases accepted: `DB_URL` ↔ `DATABASE_URL`, `DB_DRIVER` ↔ `DB_DIALECT`, `DB_USERNAME` ↔ `DB_USER`.
-
-## Diagnose first: "foreign key constraint … cannot be implemented"
-
-On a fresh Postgres run this is almost always a primary-key type mismatch: a migration declared a `uuid()` foreign key, but the referenced table's PK got created as `bigserial` because `migrationDefaults.primaryKey` defaulted to `"int"`. Fix by matching the project's PK convention via env:
-
-```bash
-CASCADE_PRIMARY_KEY=uuid
-CASCADE_UUID_STRATEGY=v7
-```
-
-Warlock projects set these in `src/config/database.ts`'s `migrationOptions`; the cascade CLI mirrors them via env — match the values exactly.
-
-## TS migrations — invoke through a TS runtime
-
-The cascade CLI ships **no TypeScript transpiler.** For `.ts` migrations, invoke through `tsx` / `ts-node` / any TS-aware runtime:
-
-```bash
-npx tsx node_modules/.bin/cascade migrate
-```
-
-If forgotten, cascade catches the import failure and prints a pointer to this pattern.
-
-## Migration file discovery
-
-Default glob: `./migrations/**/*.{ts,js,mjs,cjs}` from cwd. Override with `-p`, and **always quote the pattern** (the shell expands `**`/`*` before the binary sees it otherwise):
-
-```bash
-cascade migrate -p "src/app/**/migrations/*.ts"
-```
-
-Each file must `export default` a migration class; cascade infers the name from the filename and uses any leading `MM-DD-YYYY_HH-MM-SS` timestamp for ordering.
-
-## Operations API — programmatic equivalents
-
-```ts
-import {
-  runMigrations,
-  rollbackMigrations,
-  freshMigrate,
-  exportMigrationsSQL,
-  listExecutedMigrations,
-  createDatabase,
-  dropAllTables,
-  migrationRunner,
-} from "@warlock.js/cascade";
-import CreateUsersTable from "./migrations/create-users.migration";
-
-migrationRunner.registerMany([CreateUsersTable /* … */]);
-
-const results = await runMigrations();
-const failed = results.filter((r) => !r.success);
-```
-
-Reach for these when you need migrations inside test setup (`beforeAll(async () => { await runMigrations(); })`), container init scripts, custom CLI wrappers, or reading `_migrations` programmatically (`listExecutedMigrations()`). The Operations API returns structured data and **does not print** — the caller decides how to surface progress. (The runner still emits per-migration logs through `@warlock.js/logger`.)
-
-## Common task → command
-
-| You want to… | Command |
-|---|---|
-| Run all pending migrations | `cascade migrate` |
-| Drop everything and re-run | `cascade migrate -f` |
-| Roll back the last batch | `cascade migrate:rollback` |
-| Roll back everything | `cascade migrate:rollback --all` |
-| Generate SQL without executing | `cascade migrate --sql` |
-| Generate SQL for pending only | `cascade migrate --sql --pending-only` |
-| See what's been executed | `cascade migrate:list` |
-| Run from a non-default folder | `cascade migrate -p "<glob>"` |
-
-## Things NOT to do
-
-- Don't run `cascade migrate -f` (fresh) anywhere that could touch production — it drops everything first.
-- Don't run `migrate` from inside app code at boot. Migrations are a deploy step; coupling them to boot makes rolling restarts dangerous.
-- Don't forget to quote `-p` globs, or the shell expands them and cascade registers a single file.
-
-## See also
-
-- [`@warlock.js/cascade/write-migration/SKILL.md`](@warlock.js/cascade/write-migration/SKILL.md) — writing migration files
-- [`@warlock.js/cascade/manage-data-sources/SKILL.md`](@warlock.js/cascade/manage-data-sources/SKILL.md) — multi-database routing
+---
+name: run-cascade-cli
+description: 'Cascade''s standalone `cascade` binary + the Operations API it wraps — `cascade migrate` / `migrate:list` / `migrate:rollback` / `migrate:export-sql`, and `runMigrations` / `rollbackMigrations` / `freshMigrate` / `exportMigrationsSQL` / `listExecutedMigrations` / `createDatabase` / `dropAllTables` / `migrationRunner`. Triggers: `cascade migrate`, `migrate:list`, `migrate:rollback`, `migrate:export-sql`, `runMigrations`, `rollbackMigrations`, `freshMigrate`, `exportMigrationsSQL`, `listExecutedMigrations`, `migrationRunner`; "run migrations in deploy/CI", "reset DB for tests", "programmatic migration", "foreign key constraint cannot be implemented", `CASCADE_PRIMARY_KEY`; typical import `import { runMigrations, migrationRunner } from "@warlock.js/cascade"`. Skip: writing migration files — `@warlock.js/cascade/write-migration/SKILL.md`; competing tools `knex migrate:latest`, `prisma migrate deploy`, `typeorm migration:run`.'
+---
+
+# Run the cascade CLI / Operations API
+
+Cascade ships a standalone `cascade` binary plus a programmatic **Operations API** — named functions over the migration-runner singleton. The binary is a thin wrapper over those functions; warlock-core's CLI wraps the same code path. Use the binary from terminal / deploy scripts; use the Operations API from test setup, container init, or custom tooling.
+
+## CLI commands
+
+The standalone binary exposes four colon-keyed subcommands:
+
+```bash
+cascade migrate                 # run all pending migrations
+cascade migrate:list            # show executed migrations from _migrations
+cascade migrate:rollback        # undo the last batch
+cascade migrate:export-sql      # write .up.sql / .down.sql instead of executing
+```
+
+Flags:
+- `migrate` — `-f/--fresh` (drop everything and re-run), `-s/--sql` (export SQL instead of executing), `--pending-only`, `-c/--compact`, `-p/--path <glob>`
+- `migrate:rollback` — `-a/--all` (roll back everything), `--batches N`, `-p/--path <glob>`
+- `migrate:export-sql` — `--pending-only`, `-c/--compact`, `-p/--path <glob>`
+
+There is **no** `seed`, `db:create`, or `db:drop-tables` in the standalone binary — those need project context; use the warlock CLI when you have a Warlock app.
+
+## Configuration — env vars only
+
+No `cascade.config.{ts,js}` file. The CLI auto-loads `.env` from cwd at start.
+
+```bash
+DATABASE_URL=postgres://user:pass@host:5432/db    # one connection string …
+# … or discrete vars:
+DB_DIALECT=postgres        # or mongodb
+DB_HOST=localhost
+DB_PORT=5432
+DB_NAME=myapp
+DB_USER=postgres
+DB_PASSWORD=secret
+
+# Migration defaults — only set when overriding library defaults:
+CASCADE_PRIMARY_KEY=uuid   # uuid | int | bigInt
+CASCADE_UUID_STRATEGY=v7   # v4 | v7
+```
+
+Warlock-project aliases accepted: `DB_URL` ↔ `DATABASE_URL`, `DB_DRIVER` ↔ `DB_DIALECT`, `DB_USERNAME` ↔ `DB_USER`.
+
+## Diagnose first: "foreign key constraint … cannot be implemented"
+
+On a fresh Postgres run this is almost always a primary-key type mismatch: a migration declared a `uuid()` foreign key, but the referenced table's PK got created as `bigserial` because `migrationDefaults.primaryKey` defaulted to `"int"`. Fix by matching the project's PK convention via env:
+
+```bash
+CASCADE_PRIMARY_KEY=uuid
+CASCADE_UUID_STRATEGY=v7
+```
+
+Warlock projects set these in `src/config/database.ts`'s `migrationOptions`; the cascade CLI mirrors them via env — match the values exactly.
+
+## TS migrations — invoke through a TS runtime
+
+The cascade CLI ships **no TypeScript transpiler.** For `.ts` migrations, invoke through `tsx` / `ts-node` / any TS-aware runtime:
+
+```bash
+npx tsx node_modules/.bin/cascade migrate
+```
+
+If forgotten, cascade catches the import failure and prints a pointer to this pattern.
+
+## Migration file discovery
+
+Default glob: `./migrations/**/*.{ts,js,mjs,cjs}` from cwd. Override with `-p`, and **always quote the pattern** (the shell expands `**`/`*` before the binary sees it otherwise):
+
+```bash
+cascade migrate -p "src/app/**/migrations/*.ts"
+```
+
+Each file must `export default` a migration class; cascade infers the name from the filename and uses any leading `MM-DD-YYYY_HH-MM-SS` timestamp for ordering.
+
+## Operations API — programmatic equivalents
+
+```ts
+import {
+  runMigrations,
+  rollbackMigrations,
+  freshMigrate,
+  exportMigrationsSQL,
+  listExecutedMigrations,
+  createDatabase,
+  dropAllTables,
+  migrationRunner,
+} from "@warlock.js/cascade";
+import CreateUsersTable from "./migrations/create-users.migration";
+
+migrationRunner.registerMany([CreateUsersTable /* … */]);
+
+const results = await runMigrations();
+const failed = results.filter((r) => !r.success);
+```
+
+Reach for these when you need migrations inside test setup (`beforeAll(async () => { await runMigrations(); })`), container init scripts, custom CLI wrappers, or reading `_migrations` programmatically (`listExecutedMigrations()`). The Operations API returns structured data and **does not print** — the caller decides how to surface progress. (The runner still emits per-migration logs through `@warlock.js/logger`.)
+
+## Common task → command
+
+| You want to… | Command |
+|---|---|
+| Run all pending migrations | `cascade migrate` |
+| Drop everything and re-run | `cascade migrate -f` |
+| Roll back the last batch | `cascade migrate:rollback` |
+| Roll back everything | `cascade migrate:rollback --all` |
+| Generate SQL without executing | `cascade migrate --sql` |
+| Generate SQL for pending only | `cascade migrate --sql --pending-only` |
+| See what's been executed | `cascade migrate:list` |
+| Run from a non-default folder | `cascade migrate -p "<glob>"` |
+
+## Things NOT to do
+
+- Don't run `cascade migrate -f` (fresh) anywhere that could touch production — it drops everything first.
+- Don't run `migrate` from inside app code at boot. Migrations are a deploy step; coupling them to boot makes rolling restarts dangerous.
+- Don't forget to quote `-p` globs, or the shell expands them and cascade registers a single file.
+
+## See also
+
+- [`@warlock.js/cascade/write-migration/SKILL.md`](@warlock.js/cascade/write-migration/SKILL.md) — writing migration files
+- [`@warlock.js/cascade/manage-data-sources/SKILL.md`](@warlock.js/cascade/manage-data-sources/SKILL.md) — multi-database routing

package/skills/search-by-vector/SKILL.md

@@ -1,127 +1,127 @@
----
-name: search-by-vector
-description: "Use vector search in @warlock.js/cascade; use when you need to search by vector."
----
-
-# Use vector search
-
-Query by vector distance for semantic search. Cascade gives you the column type, the index, and the similarity query method — generating embeddings is your AI provider's job.
-
-## Schema + migration
-
-Both the column and its index are builders on the migration `this`:
-
-```ts
-import { Migration } from "@warlock.js/cascade";
-
-export default class CreateArticles extends Migration {
-  public readonly table = "articles";
-
-  public up(): void {
-    this.createTable();
-    this.id();
-    this.string("title");
-    this.text("body");
-    this.vector("embedding", 1536); // pgvector column, 1536 dims
-    this.vectorIndex("embedding", { dimensions: 1536, similarity: "cosine" });
-  }
-
-  public down(): void {
-    this.dropTable();
-  }
-}
-```
-
-`vectorIndex(column, { dimensions, similarity?, lists?, name? })` — `similarity` is `"cosine" | "euclidean" | "dotProduct"` (maps to the pgvector operator class). On Postgres this builds an **IVFFlat** index (`lists` controls the cluster count, default 100). Requires `CREATE EXTENSION vector` on the database.
-
-On MongoDB the vector index is an Atlas Search index definition (Atlas-only).
-
-## Write — store an embedding
-
-```ts
-const embedding = await ai.embed(body);
-await Article.create({ title, body, embedding });
-```
-
-Cascade stores the vector and queries against it; it doesn't compute embeddings.
-
-## Read — similarity search
-
-`.similarTo(column, embedding, alias?)` does two things at once: it adds `1 - (column <=> embedding) AS score` to the SELECT so each row carries its similarity, and it adds `ORDER BY column <=> embedding` so the database uses the vector index instead of a sequential scan. Cap the result with `.limit()`:
-
-```ts
-const queryEmbedding = await ai.embed("how does cascade vector search work?");
-
-const hits = await Article.query()
-  .similarTo("embedding", queryEmbedding) // score column defaults to "score"
-  .limit(5)
-  .get<ArticleRow & { score: number }>();
-
-// hits[0].score → similarity of the closest match
-```
-
-There is no options object — `topK` is just `.limit(k)`, and the distance metric is fixed at index creation (the `similarity` you passed to `vectorIndex`). The third argument only renames the score column (`.similarTo("embedding", vec, "distance")`). Don't add your own `.orderBy()` on the score alias afterward — it would break index usage.
-
-## Filtered similarity
-
-Chain `.where()` before `.similarTo()`:
-
-```ts
-const tenantHits = await Article.query()
-  .where("tenant_id", tenantId)
-  .where("published", true)
-  .similarTo("embedding", queryEmbedding)
-  .limit(5)
-  .get<ArticleRow & { score: number }>();
-```
-
-The DB applies the filter first (regular index), then ranks the remaining candidates by similarity (vector index).
-
-## Hybrid search — vector + full-text
-
-Cascade has `.whereFullText(fields, query)` for the text side. For best retrieval quality on long-form text, run a vector search and a full-text search and combine the results in code (re-rank or reciprocal-rank-fusion).
-
-## RAG — retrieval-augmented generation
-
-```ts
-async function answer(question: string) {
-  const queryEmbedding = await ai.embed(question);
-
-  const context = await Document.query()
-    .where("tenant_id", currentTenant.id)
-    .similarTo("embedding", queryEmbedding)
-    .limit(8)
-    .get<DocumentRow & { score: number }>();
-
-  // optional: drop low-similarity hits in code
-  const relevant = context.filter((document) => document.score >= 0.75);
-
-  const prompt = buildPrompt(question, relevant.map((document) => document.body));
-  return ai.complete(prompt);
-}
-```
-
-A score threshold isn't a query option — filter on the `score` column in code after the fetch.
-
-## Driver support
-
-| Driver | Vector |
-| --- | --- |
-| Postgres (with `CREATE EXTENSION vector`) | ✅ pgvector + IVFFlat index |
-| MongoDB Atlas (paid tier + Atlas Search index) | ✅ `$vectorSearch` aggregation stage |
-| MongoDB community / self-hosted / local | ❌ Atlas-only |
-
-For local dev with MongoDB, develop the vector path against Postgres + pgvector.
-
-## Things NOT to do
-
-- Don't pass `{ topK, metric, threshold }` to `.similarTo()` — it takes `(column, embedding, alias?)`. Use `.limit()` for topK, set the metric at `vectorIndex` creation, and threshold in code on the `score` column.
-- Don't `.orderBy()` the score alias after `.similarTo()` — it already orders by distance for index usage.
-- Don't re-embed an entire corpus when changing embedding models — vectors aren't portable across models; plan the migration.
-- Don't ship the raw vector array to clients. Drop it from the public shape with `static toJsonColumns`.
-- Don't expect `.similarTo()` without a vector index to scale. Above a few thousand rows, sequential scans dominate.
-
-## See also
-
-- [`@warlock.js/cascade/query-data/SKILL.md`](@warlock.js/cascade/query-data/SKILL.md) — `.where`, `.whereFullText`, the broader query vocabulary
-- [`@warlock.js/cache/use-cache-similarity/SKILL.md`](@warlock.js/cache/use-cache-similarity/SKILL.md) — semantic cache of LLM output
+---
+name: search-by-vector
+description: 'Vector similarity search via `.similarTo(column, embedding, alias?)` — adds a similarity `score` column and orders by vector distance so the index is used; cap results with `.limit()`. Postgres uses pgvector (IVFFlat index via `this.vectorIndex`); MongoDB needs Atlas. Schema: `this.vector(column, dimensions)` + `this.vectorIndex(column, { dimensions, similarity })`. Triggers: `.similarTo`, `this.vector`, `this.vectorIndex`, `.whereFullText`, pgvector; "semantic search", "RAG retrieval", "find similar articles", "hybrid vector + full-text"; typical import `import { Model } from "@warlock.js/cascade"`. Skip: query basics — `@warlock.js/cascade/query-data/SKILL.md`; semantic cache — `@warlock.js/cache/use-cache-similarity/SKILL.md`; competing libs `pgvector` directly, `chromadb`, `pinecone`, `weaviate`, `qdrant`.'
+---
+
+# Use vector search
+
+Query by vector distance for semantic search. Cascade gives you the column type, the index, and the similarity query method — generating embeddings is your AI provider's job.
+
+## Schema + migration
+
+Both the column and its index are builders on the migration `this`:
+
+```ts
+import { Migration } from "@warlock.js/cascade";
+
+export default class CreateArticles extends Migration {
+  public readonly table = "articles";
+
+  public up(): void {
+    this.createTable();
+    this.id();
+    this.string("title");
+    this.text("body");
+    this.vector("embedding", 1536); // pgvector column, 1536 dims
+    this.vectorIndex("embedding", { dimensions: 1536, similarity: "cosine" });
+  }
+
+  public down(): void {
+    this.dropTable();
+  }
+}
+```
+
+`vectorIndex(column, { dimensions, similarity?, lists?, name? })` — `similarity` is `"cosine" | "euclidean" | "dotProduct"` (maps to the pgvector operator class). On Postgres this builds an **IVFFlat** index (`lists` controls the cluster count, default 100). Requires `CREATE EXTENSION vector` on the database.
+
+On MongoDB the vector index is an Atlas Search index definition (Atlas-only).
+
+## Write — store an embedding
+
+```ts
+const embedding = await ai.embed(body);
+await Article.create({ title, body, embedding });
+```
+
+Cascade stores the vector and queries against it; it doesn't compute embeddings.
+
+## Read — similarity search
+
+`.similarTo(column, embedding, alias?)` does two things at once: it adds `1 - (column <=> embedding) AS score` to the SELECT so each row carries its similarity, and it adds `ORDER BY column <=> embedding` so the database uses the vector index instead of a sequential scan. Cap the result with `.limit()`:
+
+```ts
+const queryEmbedding = await ai.embed("how does cascade vector search work?");
+
+const hits = await Article.query()
+  .similarTo("embedding", queryEmbedding) // score column defaults to "score"
+  .limit(5)
+  .get<ArticleRow & { score: number }>();
+
+// hits[0].score → similarity of the closest match
+```
+
+There is no options object — `topK` is just `.limit(k)`, and the distance metric is fixed at index creation (the `similarity` you passed to `vectorIndex`). The third argument only renames the score column (`.similarTo("embedding", vec, "distance")`). Don't add your own `.orderBy()` on the score alias afterward — it would break index usage.
+
+## Filtered similarity
+
+Chain `.where()` before `.similarTo()`:
+
+```ts
+const tenantHits = await Article.query()
+  .where("tenant_id", tenantId)
+  .where("published", true)
+  .similarTo("embedding", queryEmbedding)
+  .limit(5)
+  .get<ArticleRow & { score: number }>();
+```
+
+The DB applies the filter first (regular index), then ranks the remaining candidates by similarity (vector index).
+
+## Hybrid search — vector + full-text
+
+Cascade has `.whereFullText(fields, query)` for the text side. For best retrieval quality on long-form text, run a vector search and a full-text search and combine the results in code (re-rank or reciprocal-rank-fusion).
+
+## RAG — retrieval-augmented generation
+
+```ts
+async function answer(question: string) {
+  const queryEmbedding = await ai.embed(question);
+
+  const context = await Document.query()
+    .where("tenant_id", currentTenant.id)
+    .similarTo("embedding", queryEmbedding)
+    .limit(8)
+    .get<DocumentRow & { score: number }>();
+
+  // optional: drop low-similarity hits in code
+  const relevant = context.filter((document) => document.score >= 0.75);
+
+  const prompt = buildPrompt(question, relevant.map((document) => document.body));
+  return ai.complete(prompt);
+}
+```
+
+A score threshold isn't a query option — filter on the `score` column in code after the fetch.
+
+## Driver support
+
+| Driver | Vector |
+| --- | --- |
+| Postgres (with `CREATE EXTENSION vector`) | ✅ pgvector + IVFFlat index |
+| MongoDB Atlas (paid tier + Atlas Search index) | ✅ `$vectorSearch` aggregation stage |
+| MongoDB community / self-hosted / local | ❌ Atlas-only |
+
+For local dev with MongoDB, develop the vector path against Postgres + pgvector.
+
+## Things NOT to do
+
+- Don't pass `{ topK, metric, threshold }` to `.similarTo()` — it takes `(column, embedding, alias?)`. Use `.limit()` for topK, set the metric at `vectorIndex` creation, and threshold in code on the `score` column.
+- Don't `.orderBy()` the score alias after `.similarTo()` — it already orders by distance for index usage.
+- Don't re-embed an entire corpus when changing embedding models — vectors aren't portable across models; plan the migration.
+- Don't ship the raw vector array to clients. Drop it from the public shape with `static toJsonColumns`.
+- Don't expect `.similarTo()` without a vector index to scale. Above a few thousand rows, sequential scans dominate.
+
+## See also
+
+- [`@warlock.js/cascade/query-data/SKILL.md`](@warlock.js/cascade/query-data/SKILL.md) — `.where`, `.whereFullText`, the broader query vocabulary
+- [`@warlock.js/cache/use-cache-similarity/SKILL.md`](@warlock.js/cache/use-cache-similarity/SKILL.md) — semantic cache of LLM output