@raypx-kit/drizzle-kit 0.0.0-alpha.0

package/dist/skills/drizzle-output-modes/SKILL.md

@@ -0,0 +1,51 @@
+---
+name: drizzle-output-modes
+description: "Choose and interpret drizzle-kit `--output text` vs `--output json`, reason about interactivity in non-TTY contexts, and read the human-readable missing-decisions text report. Load when deciding which `--output` mode to pass, when a drizzle-kit run in a non-TTY context needs to stay non-interactive, or when parsing a `missing_hints: N unresolved decisions` text report."
+metadata:
+  version: "1.0.0"
+---
+
+# Drizzle output modes
+
+If the `drizzle` skill has not been loaded yet this session, load it first — it carries the staleness check and the MCP-vs-CLI surface-selection rule that govern every drizzle-kit invocation.
+
+Drizzle Kit `generate` / `push` / `check` render results in one of two output modes, selected with `--output`. Output format and interactivity are separate axes: the output mode controls *how* results are rendered; interactivity controls *whether* the CLI may prompt.
+
+- `--output text` (the default) renders human-readable progress and results on stdout, with typed errors on stderr. When a command has unresolved decisions and cannot prompt, it writes the missing-decisions report (below) to stdout and exits with code 2.
+- `--output json` emits a single machine-readable JSON envelope on stdout for every status (including errors), and is always non-interactive.
+
+`check --output json` rides the same plumbing: it is a no-hint, non-interactive gate that emits an `ok` envelope when the migrations folder is valid and a `check_error` envelope for snapshot-integrity problems or unreported branch conflicts. It never reaches the missing-decisions path. The `drizzle-responses-and-errors` skill decodes the `check_error` envelope.
+
+## Interactivity
+
+A command is interactive only when it is rendering text **and** stdin is a TTY:
+
+```
+interactive = output === 'text' && !!process.stdin.isTTY
+```
+
+`--output json` is therefore always non-interactive, regardless of whether stdin is a TTY. Under `--output text`, interactivity is determined solely by whether stdin is a TTY (`!process.stdin.isTTY` means non-interactive).
+
+When the CLI is non-interactive and reaches a decision it cannot resolve from your `--hints` / `--hints-file`, it does not prompt. Under `--output json` it returns a `missing_hints` envelope; under `--output text` it prints the missing-decisions report below. The `drizzle-hints` skill covers building the reply that resolves those decisions.
+
+## Missing-decisions text report
+
+Under `--output text`, when the CLI is non-interactive (stdin is not a TTY) and at least one decision is still unresolved, it prints a human-readable report to stdout and exits with code 2. `rename_or_create` decisions are listed first (discovery order), then `confirm_data_loss` decisions (discovery order), with a continuous 1-based index across both groups. Each item shows an `Add to --hints:` block with the snippet(s) to supply; `rename_or_create` items show both a `rename` and a `create` snippet joined by `OR`.
+
+The `from` placeholders are intentionally invalid JSON — replace the angle-bracket segments with the real identifier of the entity being renamed before re-running. The report only suggests the inline `--hints '<json-array>'` form, never `--hints-file`. A two-item run renders like this:
+
+```
+missing_hints: 2 unresolved decisions
+
+1. Rename or create  —  table  public.users_v2
+   Add to --hints:
+     { "type": "rename", "kind": "table", "from": ["<schema>", "<old_name>"], "to": ["public", "users_v2"] }
+     OR
+     { "type": "create", "kind": "table", "entity": ["public", "users_v2"] }
+
+2. Confirm data loss  —  table  public.legacy_audit  (reason: non_empty)
+   Add to --hints:
+     { "type": "confirm_data_loss", "kind": "table", "entity": ["public", "legacy_audit"] }
+
+Re-run with --hints '<json-array>'. Exit code 2.
+```

package/dist/skills/drizzle-pull/SKILL.md

@@ -0,0 +1,108 @@
+---
+name: drizzle-pull
+description: Introspect an existing database into a Drizzle schema — the reverse of generate and push, which drive a database from a schema. Load whenever the task is to generate a Drizzle schema from a live database, reverse-engineer or import an existing database, or decode the result manifest or a connect/introspect failure from a pull.
+metadata:
+  version: "1.0.0"
+---
+
+# Drizzle pull
+
+If the `drizzle` skill has not been loaded yet this session, load it first — it carries the staleness check and the MCP-vs-CLI surface-selection rule that govern every drizzle-kit invocation.
+
+Pull introspects an existing database and writes a Drizzle schema from it: it connects, reads the live DDL, and emits `schema.ts`, a `relations.ts` (for the dialects that have one), and a snapshot under the configured `out` dir. It is the inverse of `generate` / `push` — those start from a schema and drive the database; pull starts from the database and writes the schema. The `drizzle-migrations` skill covers where pull sits in the overall workflow. Output format and interactivity are separate axes the same way they are for the other verbs — the `drizzle-output-modes` skill covers the text-vs-json choice — and `drizzle-responses-and-errors` decodes the envelope shapes below.
+
+## CLI form
+
+```bash
+drizzle-kit pull --output json [--config drizzle.config.ts] [--dialect <d>] [--out <dir>] [--breakpoints] [--casing camel|preserve] [--init]
+```
+
+Flag surface:
+
+- `--config` — path to `drizzle.config.ts` (default: `drizzle.config.ts` at CWD). Pull reads `dbCredentials` from the config; there is no CLI flag for the credentials object as a whole.
+- `--dialect`, `--out` — override the corresponding `defineConfig` fields. `--out` is where `schema.ts` / `relations.ts` / the snapshot are written.
+- `--url` / `--host` / `--port` / `--user` / `--password` / `--database` / `--ssl` / `--auth-token` — direct connection overrides for the corresponding `dbCredentials` fields. Most projects set these in the config file instead.
+- `--breakpoints` — emit statement-breakpoint markers in any generated migration SQL.
+- `--casing camel|preserve` — how introspected identifiers are cased in the emitted schema (`camel` camel-cases columns; `preserve` keeps the database spelling).
+- `--output json` — switches stdout to one JSON line carrying the envelope and is always non-interactive. Use it for agent / CI / scripted contexts. Under the default `--output text` pull prints human-readable progress and the result.
+- `--init` — also run the initial migration against the live database. This is a destructive write (see the `--init` note below); it adds `migrationPath` to the ok manifest.
+
+Minimal example — `drizzle.config.ts` carries the credentials, the CLI invocation is just the verb:
+
+```typescript
+// drizzle.config.ts
+import { defineConfig } from 'drizzle-kit';
+
+export default defineConfig({
+  dialect: 'postgresql',
+  out: './drizzle',
+  dbCredentials: { url: process.env.DATABASE_URL! },
+});
+```
+
+```bash
+drizzle-kit pull --output json --config drizzle.config.ts
+# → {"status":"ok","dialect":"postgresql","schemaPath":"drizzle/schema.ts","relationsPath":"drizzle/relations.ts","snapshotPath":"drizzle/meta/0000_snapshot.json"}
+```
+
+The process exits with the code that matches `status` (`0` for ok, `1` for error). Agents read both stdout (the envelope) and the exit code.
+
+## SDK form
+
+```typescript
+import { pull } from 'drizzle-kit';
+
+const response = await pull({
+  dialect: 'postgresql',
+  out: './drizzle',
+  url: process.env.DATABASE_URL!,
+});
+
+if (response.status === 'ok') {
+  // introspection succeeded; the manifest names the written files:
+  //   response.schemaPath    — always present
+  //   response.snapshotPath  — always present
+  //   response.relationsPath — present except mssql (no relations file)
+  //   response.migrationPath — present only when called with init: true
+} else {
+  // response.status === 'error'
+  // response.error.code identifies the failure, e.g. database_driver_error
+  // (connect/introspect/init failures are credential-redacted) — decode it
+  // with the drizzle-responses-and-errors skill
+}
+```
+
+`pull` is a real root SDK function. It always runs in JSON mode internally — no `--output json` flag needed at the call site — and returns the same envelope the CLI prints. In SDK form the credential fields are passed flat on the call (`url`, or the broken-out `host` / `port` / `user` / `password` / `database` set); pass `init: true` to also run the initial migration. The status is `ok` or `error` only — there is no `no_changes` branch and no `missing_hints` branch (see Contract below).
+
+## Response shape
+
+The `'ok'` envelope is a paths-manifest — it names the files pull wrote, not the introspected DDL:
+
+```jsonc
+// postgres / mysql / sqlite / turso / cockroach / singlestore — relationsPath present
+{ "status": "ok", "dialect": "postgresql", "schemaPath": "drizzle/schema.ts", "relationsPath": "drizzle/relations.ts", "snapshotPath": "drizzle/meta/0000_snapshot.json" }
+
+// mssql — relationsPath omitted (no relations file is generated)
+{ "status": "ok", "dialect": "mssql", "schemaPath": "drizzle/schema.ts", "snapshotPath": "drizzle/meta/0000_snapshot.json" }
+
+// with init: true — an initial migration was also written, so migrationPath appears
+{ "status": "ok", "dialect": "postgresql", "schemaPath": "drizzle/schema.ts", "relationsPath": "drizzle/relations.ts", "snapshotPath": "drizzle/meta/0000_snapshot.json", "migrationPath": "drizzle/0000_init/migration.sql" }
+```
+
+So the manifest is `{ schemaPath, snapshotPath, relationsPath?, migrationPath? }`: `schemaPath` and `snapshotPath` are always present; `relationsPath?` is optional and omitted for mssql; `migrationPath?` is optional and present only with `--init`. The envelope carries no inline DDL array.
+
+The `'error'` envelope, when the driver cannot connect or introspection fails:
+
+```json
+{ "status": "error", "error": { "code": "database_driver_error", "database": "postgresql", "packages": ["pg", "postgres"], "note": "<optional connection hint>" } }
+```
+
+`database_driver_error` carries only `database`, `packages`, and an optional `note` — the connection string, sql, and params are deliberately kept out of the envelope, so no credential substring ever reaches stdout. The `drizzle-responses-and-errors` skill decodes this and the other error codes. Example payloads here use placeholder paths and dialects only — never a real connection string, url, or password.
+
+## Contract
+
+Pull is ok/error only. It never emits `missing_hints`: it introspects against an empty starting DDL, constructs no hints handler, and exposes no consent surface — there are no ambiguous renames or destructive-change prompts to resolve. The only outcomes are `ok` (the manifest is returned) or a thrown typed error surfaced as the `error` envelope.
+
+## --init
+
+`--init` (CLI) / `init: true` (SDK) runs the initial migration against the live database in addition to writing the schema. That is a destructive write — it executes DDL against the connected database, not just disk — and on success it adds `migrationPath` to the ok manifest. The MCP `pull` tool surfaces this `init` escalation as a per-call destructive signal on its result; the `drizzle-responses-and-errors` skill carries the canonical shape of that signal.

package/dist/skills/drizzle-push/SKILL.md

@@ -0,0 +1,159 @@
+---
+name: drizzle-push
+description: Apply drizzle schema changes directly to a live database without writing a migration file. Load before running `drizzle-kit push` or calling the `push(...)` SDK, when syncing a Drizzle schema directly to a live DB (prototyping, dev resets, ephemeral test databases), or when the task is to push, sync, apply, or deploy a schema.
+metadata:
+  version: "1.0.0"
+---
+
+# Drizzle push
+
+If the `drizzle` skill has not been loaded yet this session, load it first — it carries the staleness check and the MCP-vs-CLI surface-selection rule that govern every drizzle-kit invocation.
+
+The CLI flag `--output json` and the SDK `push(...)` function emit the same discriminated-union envelope, and the envelope (not the stdout text) is what the agent decodes. Output format and interactivity are separate axes: `--output json` selects the machine-readable envelope and is always non-interactive, so pass it whenever an agent calls the CLI. Under the default `--output text` the CLI prompts only when stdin is a TTY; in a non-TTY it prints the missing-decisions report and exits 2 (it never hangs prompting). See the `drizzle-output-modes` skill for the two modes and the interactivity rule. The SDK runs in JSON mode internally with no flag needed at the call site. Push is the live-DB counterpart to `generate`: `generate` is offline and writes a migration SQL file to disk, `push` connects to the database and executes the diff against it. The `drizzle-generate` skill covers the offline path; the `drizzle-migrations` skill covers the day-to-day workflow that combines them.
+
+## CLI form
+
+```bash
+drizzle-kit push --output json [--config drizzle.config.ts] [--dialect <d>] [--schema <path>] [--explain] [--hints '<json>' | --hints-file ./hints.json]
+```
+
+Flag surface:
+
+- `--config` — path to `drizzle.config.ts` (default: `drizzle.config.ts` at CWD). Push reads `dbCredentials` from the config; there is no CLI flag for the credentials object as a whole.
+- `--dialect`, `--schema` — override the corresponding `defineConfig` fields.
+- `--output json` — switches stdout to one JSON line carrying the envelope and is always non-interactive. Use it for agent / CI / scripted contexts. Under the default `--output text` the CLI prompts only on a TTY and otherwise prints the missing-decisions report (exit 2).
+- `--explain` — dry-run mode. Returns planned SQL statements and computed hints instead of executing them against the database.
+- `--hints` — inline JSON array of hint resolutions (see the `drizzle-hints` skill).
+- `--hints-file` — same payload as `--hints`, read from a JSON file. Use for long hint sets.
+- `--url` / `--host` / `--port` / `--user` / `--password` / `--database` / `--ssl` / `--auth-token` — direct connection-string overrides for the corresponding `dbCredentials` fields. Most projects set these in the config file instead.
+
+Minimal example — `drizzle.config.ts` carries the credentials, the CLI invocation is just the verb:
+
+```typescript
+// drizzle.config.ts
+import { defineConfig } from 'drizzle-kit';
+
+export default defineConfig({
+  dialect: 'postgresql',
+  schema: './src/db/schema.ts',
+  dbCredentials: { url: process.env.DATABASE_URL! },
+});
+```
+
+```bash
+drizzle-kit push --output json --config drizzle.config.ts
+# → {"status":"ok","dialect":"postgresql"}
+```
+
+The process exits with the code that matches `status` (see Response envelope below). Agents read both stdout (the envelope) and the exit code.
+
+## SDK form
+
+```typescript
+import { push } from 'drizzle-kit';
+
+const response = await push({
+  dialect: 'postgresql',
+  schema: './src/db/schema.ts',
+  url: process.env.DATABASE_URL!,
+});
+
+if (response.status === 'ok') {
+  // schema applied to the live database
+} else if (response.status === 'no_changes') {
+  // live DB already matches the schema — nothing executed
+} else if (response.status === 'missing_hints') {
+  // response.unresolved lists ambiguities or destructive ops — see the drizzle-hints skill
+} else if (response.status === 'error') {
+  // response.error.code identifies the failure — see drizzle-responses-and-errors
+}
+```
+
+The SDK is the public-surface entry point. It always runs in JSON mode internally — no `--output json` flag needed at the call site — and returns the same envelope the CLI prints. In SDK form the credential fields are passed flat on the call (`url`, or the broken-out `host`/`port`/`user`/`password`/`database` set) — there is no `dbCredentials` wrapper and no `drizzle.config.ts` file is required. Narrow on `response.status` to extract typed branches:
+
+- `'ok'` → `response.dialect` (plus `response.statements`, `response.hints` in explain mode).
+- `'no_changes'` → `response.dialect`.
+- `'missing_hints'` → `response.unresolved` (array of items).
+- `'error'` → `response.error.code` plus per-code metadata.
+
+The SDK does not throw on user-level failures — every outcome flows through the envelope. Unexpected runtime exceptions are wrapped as `status: 'error'` with `code: 'internal_error'`.
+
+## Response shape
+
+Push's `'ok'` envelope is `{ status, dialect }` — no `migration_path`, since push executes the diff against the live DB rather than writing a file. `'ok'` (explain) carries `{ status, dialect, statements, hints }`. `'no_changes'`, `'missing_hints'`, and `'error'` are shared across operations. Full envelope shapes, exit-code mapping, and per-code error metadata live in the `drizzle-responses-and-errors` skill's response-envelope section.
+
+`'missing_hints'` (exit 2) means the diff is ambiguous or unsafe — the resolution loop lives in the `drizzle-hints` skill. The most common error codes for `push` are `config_validation_error`, `config_connection_error`, `database_driver_error`, `query_error`, `unsupported_schema_change`, `invalid_hints`, `required_packages_error`, `internal_error`.
+
+## Connection
+
+Push requires a live database connection. In `drizzle.config.ts` (CLI form) the credentials nest under a `dbCredentials` object; in SDK form the same fields are passed flat on the `push(...)` call — no `dbCredentials` wrapper. The shape varies per dialect; common fields are `url` (preferred when the driver supports it) or the broken-out `host` / `port` / `user` / `password` / `database` set, plus `ssl` for TLS and `authToken` for turso/libsql. The per-dialect shapes below show the config (`dbCredentials`) form; in the SDK, drop the wrapper and pass these fields directly on the call.
+
+```typescript
+// postgresql / cockroach
+dbCredentials: { url: process.env.DATABASE_URL! }
+// or: { host, port, user, password, database, ssl }
+
+// mysql / singlestore
+dbCredentials: { url: process.env.DATABASE_URL! }
+// or: { host, port, user, password, database }
+
+// sqlite
+dbCredentials: { url: 'file:./local.db' }
+
+// turso (libsql)
+dbCredentials: { url: process.env.TURSO_URL!, authToken: process.env.TURSO_AUTH_TOKEN }
+
+// mssql
+dbCredentials: { url: process.env.MSSQL_URL! }
+// or: { server, port, user, password, database }
+```
+
+Secrets belong in environment variables (`process.env.DATABASE_URL`, etc.) — `drizzle.config.ts` typically ships with the repo, so hard-coded credentials leak through source control once committed. When credentials are absent or malformed, push returns `status: 'error'` with `code: 'config_connection_error'`; when the driver itself fails to connect (wrong host, bad TLS, server down), `code: 'database_driver_error'`. The `drizzle-responses-and-errors` skill decodes both.
+
+## Destructive changes
+
+When push would drop a non-empty table, column, schema, or view, drop a primary key, change a column's SQL type, or recreate a SQLite table to add a `NOT NULL` column (which wipes its rows), it does not execute. Instead it returns `status: 'missing_hints'` with `unresolved` items of `type: 'confirm_data_loss'`. The agent must approve each item with a matching `Hint` and re-invoke.
+
+Adding `NOT NULL` or `UNIQUE` on the server dialects (postgresql, mysql, mssql, cockroach, singlestore) does not trigger a confirmation request — the `ALTER` runs and the database enforces the constraint, rejecting a genuine violation cleanly. Only SQLite's `add_not_null` is a `confirm_data_loss`, because SQLite has no in-place path to add the column and so recreates the table and deletes all rows (reason `table_recreate`).
+
+The `confirm_data_loss` kinds that fire here: `table`, `column`, `schema`, `view`, `primary_key`, and (sqlite / turso only) `add_not_null`. The reasons (`non_empty`, `table_recreate`, `type_change`) and the kinds they apply to are catalogued in the `drizzle-hints` skill's reasons section. See the `drizzle-hints` skill for the full resolution loop (parse `unresolved` → build a `Hint` per item → pass `hints` back → re-invoke).
+
+Every entity tuple leads with a namespace segment for uniform arity, but only postgresql, cockroach, and mssql have a real schema namespace (the `schema` entity kind is wired only for those three). On the schemaless dialects (mysql, sqlite, singlestore) that leading segment is a synthesized `'public'` placeholder, not a real schema — echo it verbatim; on a schemaless dialect it is filler, never build a separate `schema` rename or create from it.
+
+## Dialect notes
+
+Per-dialect quirks (postgresql, mysql, sqlite, mssql, cockroach, singlestore) — the same diff engine and dialect surface drives both `generate` and `push`, so the notes are shared. See the `drizzle-migrations` skill's dialect-notes section.
+
+## Examples
+
+```bash
+# Happy path — diff applied against the live DB
+drizzle-kit push --output json --config drizzle.config.ts
+# → {"status":"ok","dialect":"postgresql"}
+
+# Idempotent re-run — live DB already matches the schema
+drizzle-kit push --output json --config drizzle.config.ts
+# → {"status":"no_changes","dialect":"postgresql"}
+
+# Destructive change — caller must supply confirm_data_loss hints and retry
+drizzle-kit push --output json --config drizzle.config.ts
+# → {"status":"missing_hints","unresolved":[{"type":"confirm_data_loss","kind":"column","entity":["public","users","legacy_id"],"reason":"non_empty"}]}
+# (resolution loop: see the drizzle-hints skill)
+
+# Hard error — wrong credential shape for the driver
+drizzle-kit push --output json --config drizzle.config.ts
+# → {"status":"error","error":{"code":"config_connection_error","driver":"pg","params":["url"]}}
+```
+
+SDK equivalent of the happy path:
+
+```typescript
+import { push } from 'drizzle-kit';
+
+const r = await push({
+  dialect: 'postgresql',
+  schema: './src/db/schema.ts',
+  url: process.env.DATABASE_URL!,
+});
+if (r.status === 'ok') console.log('applied');
+```

package/dist/skills/drizzle-responses-and-errors/SKILL.md

@@ -0,0 +1,156 @@
+---
+name: drizzle-responses-and-errors
+description: Decode the drizzle-kit response JSON envelope, error codes, and exit codes — from the CLI `--output json` output or any drizzle-kit SDK return value. Load whenever drizzle-kit output contains a non-zero exit, an error code (`config_validation_error`, `database_driver_error`, `invalid_hints`, `unsupported_schema_change`, etc.), or any drizzle-kit JSON response needs parsing or inspection.
+metadata:
+  version: "1.0.0"
+---
+
+# Drizzle responses and errors
+
+If the `drizzle` skill has not been loaded yet this session, load it first — it carries the staleness check and the MCP-vs-CLI surface-selection rule that govern every drizzle-kit invocation.
+
+Both invocation surfaces share one envelope: the CLI prints it on stdout when `--output json` is passed, and the SDK functions `generate(...)` / `push(...)` / `check(...)` return the same object. The discriminator is always `status`. Decoding logic written for one surface works on the other. This skill does not invoke commands or author schemas — see `drizzle-generate` and `drizzle-push` for invocation, `drizzle-hints` for the `missing_hints` resolution loop.
+
+## Response envelope
+
+The discriminated union (identical for CLI stdout and SDK return value):
+
+| status            | exit code | shape                                                   |
+| ----------------- | --------- | ------------------------------------------------------- |
+| `'ok'`            | 0         | `{ status, dialect, ... }` (per-operation extras below) |
+| `'no_changes'`    | 0         | `{ status, dialect }`                                   |
+| `'missing_hints'` | 2         | `{ status, unresolved: MissingHint[] }`                 |
+| `'error'`         | 1         | `{ status, error: { code, ...meta } }`                  |
+
+Per-operation extras on `'ok'`:
+
+- `generate` (write mode) — `{ status, dialect, migration_path }`
+- `push` (write mode) — `{ status, dialect }`
+- `pull` — `{ status, dialect, schemaPath, snapshotPath, relationsPath?, migrationPath? }` (`relationsPath?` omitted for mssql; `migrationPath?` only with `--init`). `pull` is ok-or-error only — never `missing_hints`, never `no_changes`.
+- `export` — `{ status, dialect, statements, warnings }` (the individual SQL statements plus rendered warnings — there is no joined `sql` field).
+- `up` — `{ status, dialect, upgraded }` (`upgraded` is the array of rewritten snapshot paths; `[]` means a no-op).
+- `--explain` (either command, non-empty diff) — `{ status, dialect, statements, hints }`
+
+`'missing_hints'` carries `unresolved`, an array of items the agent must resolve before retrying. Each item is `{ type: 'rename_or_create', kind, entity }` or `{ type: 'confirm_data_loss', kind, entity, reason, reason_details? }`. The resolution loop lives in the `drizzle-hints` skill.
+
+The table above describes `--output json`. Under `--output text` + non-TTY the same `missing_hints` information renders as the human-readable missing-decisions report on stdout, still exiting with code 2 — see the `drizzle-output-modes` skill for the text-report shape.
+
+`'error'` carries `error.code` plus `meta` keys (variable per code). The runtime serializer flattens `{ code, ...meta }` into the `error` object — `code` is always present; the remaining keys vary. The envelope is the only shape an agent observes; no other fields are surfaced.
+
+Exit code is the canonical second signal — agents spawning the CLI can branch on either the envelope or the exit code; agents using the SDK only see the envelope.
+
+## Error codes
+
+The canonical subset surfacing from `generate` and `push`. `code` is the discriminator; `meta` keys are listed alongside.
+
+| code                                | when                                                                                | meta keys                                                       |
+| ----------------------------------- | ----------------------------------------------------------------------------------- | --------------------------------------------------------------- |
+| `invalid_hints`                     | hints payload could not be loaded, parsed, validated, or matched to the diff        | `source: 'file'\|'inline'`, `path?`, `issues?`, `kind?`, `from?` |
+| `unsupported_schema_change`         | the diff would emit DDL the target dialect cannot execute (see variants below)      | `kind`, plus per-variant keys                                   |
+| `check_error`                       | `check` found a snapshot-integrity problem or unreported branch conflicts (see below) | `kind: 'unsupported'\|'malformed'\|'non_latest'\|'conflicts'`, `snapshot?`, `conflicts?`, `details?` |
+| `query_error`                       | runtime SQL against the live DB threw                                               | `sql`, `params`                                                 |
+| `internal_error`                    | uncaught exception escaped the run boundary — likely a bug to report                | `message`                                                       |
+| `config_validation_error`           | `drizzle.config.ts` failed shape validation                                         | `issues?` (zod-style records)                                   |
+| `config_file_not_found_error`       | config path did not resolve to a file                                               | `path`                                                          |
+| `schema_files_not_found_error`      | schema glob(s) matched zero files                                                   | `paths`                                                         |
+| `missing_required_params_error`     | a required CLI flag or config field was absent                                      | `params`                                                        |
+| `ambiguous_params_error`            | a flag conflicts with a `defineConfig` field (or two flags collide)                 | `command`, `configOption`                                       |
+| `unsupported_command_dialect_error` | the requested command isn't valid for the chosen dialect                            | `command`, `dialect?`                                           |
+| `config_connection_error`           | `dbCredentials` shape doesn't match the chosen driver                               | `driver`, `params`, `command?`                                  |
+| `database_driver_error`             | driver-specific connect failure — usually a missing or version-mismatched package; also arises from `pull`'s connect/introspect span and its `--init` migrate span | `database`, `packages`, `note?`                                 |
+| `orm_version_error`                 | `drizzle-orm` is missing, too old, or `drizzle-kit` itself is outdated              | `kind: 'orm_missing'\|'orm_too_old'\|'kit_outdated'`            |
+| `required_packages_error`           | one or more dialect driver packages need installing                                 | `packages`                                                      |
+| `migrations_outdated_error`         | migrations folder format is outdated and needs upgrading                            | `out`                                                           |
+
+Ordering above is roughly most-likely-first from `generate` / `push`. Other codes can surface (see the live `drizzle-kit` source); the table covers the curated subset relevant to the day-to-day workflow.
+
+## Unsupported schema changes
+
+`unsupported_schema_change` is a discriminated meta union — `meta.kind` selects the variant.
+
+| meta.kind                            | dialect(s)         | meta keys                                                       |
+| ------------------------------------ | ------------------ | --------------------------------------------------------------- |
+| `drop_pk_dependency`                 | mysql, singlestore | `kind`, `table`, `columns`, `blocking_fks`                      |
+| `fk_target_not_unique`               | mysql, singlestore | `kind`, `table`, `columns`, `table_to`, `columns_to`            |
+| `rename_blocked_by_check_constraint` | mssql              | `kind`, `schema`, `table`, `from`, `to`                         |
+| `rename_schema_unsupported`          | mssql              | `kind`, `from`, `to`, `dialect: 'mssql'`                        |
+
+When fired:
+
+- `drop_pk_dependency` — `ALTER TABLE … DROP PRIMARY KEY` is rejected because a foreign key references the dropped columns and no covering UNIQUE index exists. Add a UNIQUE on those columns first, then drop.
+- `fk_target_not_unique` — `CREATE FOREIGN KEY` is rejected because the referenced columns on `table_to` are neither UNIQUE nor a PRIMARY KEY. Add a UNIQUE on `columns_to` first.
+- `rename_blocked_by_check_constraint` — `sp_rename` of `schema.table.from` is rejected because the column appears in a CHECK constraint. Drop the constraint, rename, recreate the constraint.
+- `rename_schema_unsupported` — MSSQL does not support schema rename at all. Recreate the schema and move objects manually, or keep the old schema name.
+
+## Check errors
+
+`check_error` surfaces from the `check()` SDK export and `drizzle-kit check`, returning the envelope on integrity or conflict failures exactly as the CLI does. It also surfaces from `generate` / `migrate` when their pre-flight migrations-folder gate fails. It exits with code 1 and carries a `kind` discriminator.
+
+| meta.kind     | meta keys                | when fired                                                              |
+| ------------- | ------------------------ | ---------------------------------------------------------------------- |
+| `unsupported` | `kind`, `snapshot`       | a snapshot was written by a newer drizzle-kit and cannot be read       |
+| `malformed`   | `kind`, `snapshot`       | a snapshot could not be parsed                                         |
+| `non_latest`  | `kind`, `snapshot`       | a snapshot is not at the latest internal version and must be upgraded  |
+| `conflicts`   | `kind`, `conflicts`, `details` | branches in the migrations folder do not commute (run without `--ignore-conflicts`) |
+
+For the integrity kinds, `snapshot` names the offending file. For `conflicts`, `conflicts` is the count and `details` is an array of length `conflicts`; each entry is `{ parentId, parentPath?, branches }` where `branches` is always a two-element array of `{ leafId, leafPath, statementDescription }` describing the two diverging branches off the common parent. `leafId` / `leafPath` are `null` when a branch chain is empty.
+
+## Decoding pattern (CLI + SDK)
+
+Narrow on `status` and then on `error.code`:
+
+```typescript
+import { generate } from 'drizzle-kit';
+
+const response = await generate({ dialect: 'postgresql', schema: './src/db/schema.ts', out: './drizzle' });
+
+switch (response.status) {
+  case 'ok':
+    // response.dialect is present; response.migration_path when not in explain mode
+    break;
+  case 'no_changes':
+    // response.dialect is present; nothing to do
+    break;
+  case 'missing_hints':
+    // response.unresolved holds the items to resolve (see drizzle-hints)
+    break;
+  case 'error':
+    switch (response.error.code) {
+      case 'config_file_not_found_error':
+        // response.error.path
+        break;
+      case 'invalid_hints':
+        // response.error.source, response.error.issues, etc.
+        break;
+      case 'check_error':
+        // migrations-folder pre-flight gate failed; response.error.kind, response.error.snapshot / conflicts / details
+        break;
+      // ...other codes from the table above
+    }
+    break;
+}
+```
+
+CLI equivalent — parse `stdout` as JSON, switch on `response.status` the same way. Exit codes map: `exit 0` for `ok` / `no_changes`, `exit 1` for `error`, `exit 2` for `missing_hints`.
+
+## Troubleshooting
+
+Common failure modes and their fixes — keyed by `error.code` / `meta.kind`:
+
+- `config_file_not_found_error` — `meta.path` names the missing file. Pass `--config <path>` (CLI) or point the SDK call's `configPath` at the right location; the default lookup is `drizzle.config.ts` in CWD.
+- `schema_files_not_found_error` — `meta.paths` lists the globs that resolved to nothing. Use a concrete `.ts` extension in the path, or expand the glob to cover the directory the schema lives in.
+- `config_validation_error` — `meta.issues` carries a zod-style array (`path`, `message`). Fix the named fields in `drizzle.config.ts`; the most common cause is a missing `dialect` or a `dbCredentials` block whose shape doesn't match the dialect.
+- `missing_required_params_error` — `meta.params` names the missing fields (e.g. `['dialect']`). Add them via config or CLI flag.
+- `ambiguous_params_error` — a flag and a `defineConfig` field both set the same value. Pick one source of truth — `meta.command` plus `meta.configOption` name the conflict.
+- `config_connection_error` — the `dbCredentials` keys don't match what `meta.driver` expects. `meta.params` lists the keys the driver needs. Reshape `dbCredentials` accordingly.
+- `database_driver_error` — driver could not connect. `meta.packages` lists the npm packages required for the driver; install them. `meta.note` may carry a connection-specific hint (e.g. SSL). Beyond `push`, this also fires from `pull`'s connect/introspect span and the `--init` migrate span — the meta is always the redacted `{ database, packages, note? }`; the connection string, SQL, and params are never spread into the envelope.
+- `orm_version_error` — `meta.kind` discriminates: `orm_missing` (install `drizzle-orm`), `orm_too_old` (bump `drizzle-orm`), `kit_outdated` (bump `drizzle-kit` itself).
+- `required_packages_error` — `meta.packages` lists the npm packages to install. Common for dialect drivers (`pg`, `mysql2`, `better-sqlite3`, `@libsql/client`, `mssql`).
+- `unsupported_command_dialect_error` — the command isn't supported for `meta.dialect`. Use a different command or switch dialects.
+- `migrations_outdated_error` — the migrations folder under `meta.out` uses an older snapshot format. Run `drizzle-kit up` to migrate the folder forward.
+- `invalid_hints` — discriminated by which keys are present in `meta`: `path` means a file read failed, `issues` means schema validation failed, `kind` + `from` together mean a `rename` hint's `from` tuple did not match any deleted entity. For schema-validation failures, fix the named issues; for a `from` mismatch, correct the tuple (the entity must be one the diff would otherwise delete).
+- `unsupported_schema_change` — refer to the variant table above; each variant has a specific remediation path.
+- `query_error` — the live DB threw on `meta.sql` with `meta.params`. Run the same query manually against the target DB to surface the underlying DBMS error; fix the schema or the data.
+- `internal_error` — an unexpected exception escaped. `meta.message` carries the underlying error text. File an issue if reproducible; the SDK never throws for known failures, only for genuine bugs.
+
+For `missing_hints` (status, not an error code) — see the `drizzle-hints` skill for the resolve-and-retry loop. For workflow context — when to use `generate` vs `push`, how migrations folders work — see `drizzle-migrations`.

package/package.json

@@ -0,0 +1,69 @@
+{
+  "name": "@raypx-kit/drizzle-kit",
+  "version": "0.0.0-alpha.0",
+  "description": "drizzle-kit's CLI and defineConfig without the unused prebuilt API and payload bundles.",
+  "homepage": "https://github.com/raypx/raypx-kit/tree/canary/packages/drizzle-kit",
+  "license": "MIT",
+  "author": {
+    "name": "Zack",
+    "email": "heyloyep@gmail.com"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/raypx/raypx-kit.git",
+    "directory": "packages/drizzle-kit"
+  },
+  "bin": {
+    "drizzle-kit": "./dist/bin.cjs"
+  },
+  "files": [
+    "dist",
+    "LICENSE",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.mts",
+        "default": "./dist/index.mjs"
+      },
+      "require": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      }
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "check": "bun --check --tsconfig-override tsconfig.json",
+    "test": "bun --bun vp test --run",
+    "test:unit": "bun --bun vp test --run --passWithNoTests --exclude '**/component.test.{ts,tsx}' --exclude '**/*.component.test.{ts,tsx}' --exclude '**/*.integration.test.{ts,tsx}'",
+    "test:integration": "bun --bun vp test --run --passWithNoTests integration.test",
+    "test:component": "bun --bun vp test --run --passWithNoTests component.test",
+    "test:coverage": "bun --bun vp test --run --passWithNoTests --coverage --coverage.reporter=text --coverage.reporter=json --coverage.reporter=lcov",
+    "build": "bun src/extract.ts",
+    "pack:check": "bun pm pack --dry-run --ignore-scripts"
+  },
+  "dependencies": {
+    "@drizzle-team/brocli": "^0.12.0",
+    "@js-temporal/polyfill": "^0.5.1",
+    "esbuild": "^0.25.10",
+    "get-tsconfig": "^4.13.6",
+    "jiti": "^2.6.1"
+  },
+  "devDependencies": {
+    "@types/semver": "^7.8.0",
+    "@vitest/coverage-v8": "^5.0.5",
+    "drizzle-kit": ">=1.0.0-rc.5-5935859 <1.0.0-rc.5-z",
+    "drizzle-orm": ">=1.0.0-rc.5-5935859 <1.0.0-rc.5-z",
+    "semver": "^7.8.5"
+  },
+  "engines": {
+    "node": ">=22.14"
+  }
+}