drizzle-kit SDK + CLI envelope refactor

Introduce a programmatic SDK (drizzle-kit/src/sdk/) for generate/push,
unify the CLI around an envelope contract (drizzle-kit/src/cli/contract.ts),
and extract shared generate/push pipelines into schema.ts. Adds SDK
conformance + regression tests and reworks affected CLI/dialect/api
modules accordingly.

Author: dankochetov

.claude/skills/tests/SKILL.md

@@ -7,6 +7,18 @@ description: Anything test-related in the drizzle-orm monorepo — running, writ
 
 This monorepo's tests fall into two buckets: **unit-style** (no DB, run anywhere) and **DB-backed** (need a real Postgres / MySQL / MariaDB / CockroachDB / MSSQL / SingleStore on a specific port). The DB-backed ones read connection-string env vars from `drizzle-kit/.env`, which itself maps to ports owned by `compose/*.yml`. If any of those three layers is missing — env file, DB container, port match — the test fails with a confusing error (most often `connect ECONNREFUSED` or `process.env.X is not set`). This skill is the fast path through the setup so the user doesn't waste time debugging environment instead of code.
 
+## ⛔ Hard rule — never spawn Docker from test code, test runs, or agent narration
+
+**This rule has four halves. Violating any one of them reads to the user as "tests spawned Docker again".**
+
+**1. Test code must not spawn containers.** Never `import Docker`/`dockerode`/`testcontainers`/`GenericContainer` and never `execSync('docker ...')` in a new test file. The legacy `drizzle-kit/tests/<dialect>/mocks.ts::createDockerDB()` and `integration-tests/tests/{pg,mysql,cockroach,mssql,bun,seeder}/*.test.ts::createDockerDB()` paths exist for historical reasons — DO NOT add new ones, and DO NOT call existing ones from new tests. Wrap new DB-backed tests in `describe.skipIf(!process.env.X)` so a missing env var skips silently.
+
+**2. Latent trigger: legacy `?? createDockerDB()` fallbacks are still wired up.** Many `integration-tests/tests/{pg,mysql,cockroach,mssql,bun,seeder}/*.test.ts` files contain `process.env.X ?? await createDockerDB()`. Running `pnpm --filter integration-tests test:*` without the matching env var will silently spin up a container via `dockerode` — even if you've already brought DBs up via `compose/dockers.sh`. The same fallthrough exists in `drizzle-kit/tests/<dialect>/mocks.ts::prepareTestDatabase()`. **Setting env vars is not optional — it is what prevents Docker spawn.** Always export the connection string before invoking these scripts, even when "just running the suite to see what passes". If you discover a new test using this pattern, flag it as tech debt — do not extend it.
+
+**3. Agent narration must not tempt operators into `docker run`.** When you (or a spawned subagent) summarize how to run a new DB-backed test, **always** reference `bash compose/dockers.sh up <dialect>` plus the connection-string env var. Never write "this test starts a postgres container" or suggest `docker run` in a final message — the user pattern-matches that as "tests spawned Docker again", even when the underlying code is well-behaved.
+
+**4. Spawned subagents do not inherit this skill.** When delegating any test-writing or test-running work via the Agent tool, paste rules 1–3 verbatim into the subagent prompt. Subagents only see the prompt you give them, not the project's `.claude/skills/` directory. If a subagent's diff adds `import Docker` or its summary tells the operator to `docker run`, that's the failure mode this rule prevents.
+
 ## Workflow (always run in this order)
 
 ### 1. Ensure `drizzle-kit/.env` exists

drizzle-kit/.gitignore

@@ -10,6 +10,7 @@ tests/**/tmp/
 !README.md
 !CONTRIBUTING.md
 !JSON_CONTRACT.md
+!SDK.md
 
 !.eslint
 !.gitignore

drizzle-kit/JSON_CONTRACT.md

@@ -13,6 +13,41 @@ It is written for tools and services that call Drizzle Kit programmatically.
 
 When `--json` is enabled, callers should treat `stdout` as the JSON channel. Each command invocation writes a single JSON object to `stdout`.
 
+## Programmatic API
+
+The same JSON contract documented in this file is available as typed root-level exports of the `drizzle-kit` package for programmatic callers — agents, build tools, custom orchestrators. The CLI and SDK share one implementation; the response shapes, status discriminator, hint vocabulary, and error codes documented below apply identically to SDK return values.
+
+```typescript
+import { generate, push } from 'drizzle-kit';
+import type { GenerateJsonResponse } from 'drizzle-kit';
+
+const response: GenerateJsonResponse = await generate({
+  dialect: 'postgresql',
+  schema: './src/db/schema.ts',
+  out: './drizzle',
+});
+
+if (response.status === 'missing_hints') {
+  // Resolve unresolved items and re-invoke with `hints`. See SDK.md for the full pattern.
+}
+```
+
+What the SDK gives you over the CLI:
+
+- Typed inputs (`GenerateOptions`, `PushOptions`) — your editor narrows option names and types
+- Typed responses (`GenerateJsonResponse`, `PushJsonResponse`) — the union discriminator on `status` lets TypeScript narrow into the `ok`, `no_changes`, `missing_hints`, and `error` branches
+- No `--json` flag handling, no stdout parsing — the response object is what the JSON mode would have printed
+
+Cross-reference map:
+
+- All `status` values — see [Response statuses](#response-statuses)
+- All `kind` values inside `unresolved` — see [Hints flow](#hints-flow) and the kinds catalog under [status: "missing_hints"](#status-missing_hints)
+- All `error.code` values — see [Error codes](#error-codes)
+- The `--explain` envelope (SDK callers receive the same payload when `explain: true` is passed) — see [`--explain` in JSON mode](#--explain-in-json-mode)
+- The recommended retry-with-hints flow (the SDK equivalent) — see [Recommended automation flow](#recommended-automation-flow)
+
+For a full end-to-end example including `missing_hints` handling, see [SDK.md](./SDK.md).
+
 ## Hints flow
 
 Some schema changes are ambiguous (rename vs. create+delete) or unsafe to apply automatically (drops on non-empty data, NOT NULL on nullable columns, etc.). In interactive mode, Drizzle Kit prompts the user. In JSON mode there are no prompts: callers either supply hints up front, or receive a `status: "missing_hints"` response and reply with hints.

drizzle-kit/README.md

@@ -9,6 +9,8 @@ Check the full documentation on [the website](https://orm.drizzle.team/kit-docs/
 
 For machine-readable CLI behavior in non-interactive workflows, see [JSON mode and hints contract](./JSON_CONTRACT.md).
 
+For programmatic / agent consumption, see the [SDK documentation](./SDK.md) — the same JSON contract is available as typed root-level exports (`import { generate, push } from 'drizzle-kit'`).
+
 
 ### How it works
 

drizzle-kit/SDK.md

@@ -0,0 +1,139 @@
+# Drizzle Kit SDK
+
+The same JSON contract the `drizzle-kit` CLI emits is available as typed root-level exports for programmatic callers — agents, build tools, custom orchestrators. The CLI and SDK share one implementation; behavior, status discriminators, hint vocabulary, and error codes are identical to what is documented in [JSON_CONTRACT.md](./JSON_CONTRACT.md).
+
+This document covers the public SDK surface. For the full machine-readable contract (status table, hint catalog, error code table), read [JSON_CONTRACT.md](./JSON_CONTRACT.md).
+
+## Install
+
+```bash
+npm install drizzle-kit drizzle-orm
+```
+
+## Public surface
+
+Three root-level values plus six type aliases:
+
+| Export | Kind | Purpose |
+|---|---|---|
+| `defineConfig` | function | Type-checked Drizzle config builder (CLI parity) |
+| `generate` | async function | Programmatic equivalent of `drizzle-kit generate --json` |
+| `push` | async function | Programmatic equivalent of `drizzle-kit push --json` |
+| `Config` | type | Discriminated union of dialect configs |
+| `GenerateOptions` | type | Input shape for `generate` |
+| `PushOptions` | type | Input shape for `push` |
+| `GenerateJsonResponse` | type | Discriminated response union for `generate` |
+| `PushJsonResponse` | type | Discriminated response union for `push` |
+| `MissingHintsResponse` | type | The `status: 'missing_hints'` branch of both responses |
+
+All other public-surface details (status discriminator values, hint kinds, error codes) live in [JSON_CONTRACT.md](./JSON_CONTRACT.md) and apply identically to SDK return values — they are not restated here.
+
+```typescript
+import { defineConfig, generate, push } from 'drizzle-kit';
+import type {
+  Config,
+  GenerateJsonResponse,
+  GenerateOptions,
+  MissingHintsResponse,
+  PushJsonResponse,
+  PushOptions,
+} from 'drizzle-kit';
+```
+
+## Minimal `generate` example
+
+```typescript
+import { generate } from 'drizzle-kit';
+import type { GenerateJsonResponse } from 'drizzle-kit';
+
+const response: GenerateJsonResponse = await generate({
+  dialect: 'postgresql',
+  schema: './src/db/schema.ts',
+  out: './drizzle',
+});
+
+if (response.status === 'ok') {
+  console.log(`Generated migration at ${response.migration_path}`);
+} else if (response.status === 'no_changes') {
+  console.log('Schema in sync — no migration needed');
+} else if (response.status === 'error') {
+  console.error(`generate failed (${response.error.code})`);
+  process.exit(1);
+}
+```
+
+## Minimal `push` example
+
+```typescript
+import { push } from 'drizzle-kit';
+import type { PushJsonResponse } from 'drizzle-kit';
+
+const response: PushJsonResponse = await push({
+  dialect: 'postgresql',
+  schema: './src/db/schema.ts',
+  url: process.env.DATABASE_URL!,
+});
+
+if (response.status === 'ok') {
+  console.log(`Applied schema changes to the live ${response.dialect} database`);
+} else if (response.status === 'no_changes') {
+  console.log('Database already in sync');
+} else if (response.status === 'error') {
+  console.error(`push failed (${response.error.code})`);
+  process.exit(1);
+}
+```
+
+## Handling `status: 'missing_hints'`
+
+The most important agent-facing branch. When `generate` or `push` detects an ambiguity (a rename vs. drop+create, a destructive operation needing confirmation, a new schema declaration), it returns `status: 'missing_hints'` with an `unresolved` array describing each ambiguity. The caller picks a resolution for each item, builds a hint array, and re-invokes with the same options plus `hints`.
+
+Hint vocabulary (which `kind` values are valid, what each `meta` shape contains) is documented in [JSON_CONTRACT.md Hints flow](./JSON_CONTRACT.md#hints-flow) — this guide shows only the SDK call pattern.
+
+```typescript
+import { generate } from 'drizzle-kit';
+import type { GenerateJsonResponse, MissingHintsResponse } from 'drizzle-kit';
+
+async function generateWithHints(): Promise<GenerateJsonResponse> {
+  const baseOptions = {
+    dialect: 'postgresql' as const,
+    schema: './src/db/schema.ts',
+    out: './drizzle',
+  };
+
+  // First call — no hints.
+  const first: GenerateJsonResponse = await generate(baseOptions);
+  if (first.status !== 'missing_hints') return first;
+  // first.status === 'missing_hints' from here on — `unresolved` is now narrowed.
+
+  // Build resolutions. Each unresolved item dictates which `kind` and `meta` to send.
+  // See JSON_CONTRACT.md "Catalog: kinds in unresolved items" for the full mapping.
+  const hints = first.unresolved.map((item) => resolveHint(item));
+
+  // Re-invoke with hints serialized as JSON string (matches CLI --hints flag).
+  return generate({
+    ...baseOptions,
+    hints: JSON.stringify(hints),
+  });
+}
+
+function resolveHint(item: MissingHintsResponse['unresolved'][number]): unknown {
+  // Application-specific resolution policy — agent prompts, user prompts, or static rules.
+  // The returned object must match the `Hint` shape documented in JSON_CONTRACT.md.
+  throw new Error(`Provide a hint resolution for ${JSON.stringify(item)}`);
+}
+```
+
+Notes:
+
+- `hints` is passed as a JSON string (mirrors `--hints` on the CLI). For long hint sets, use `hintsFile` with a path to a JSON file instead.
+- A second `missing_hints` response after providing hints means the hint set was incomplete or invalid — see [JSON_CONTRACT.md Error codes](./JSON_CONTRACT.md#error-codes) for `invalid_hints` diagnostics.
+- The same flow applies to `push` — substitute `push` and `PushJsonResponse` everywhere.
+
+## Cross-references
+
+- [JSON_CONTRACT.md Programmatic API](./JSON_CONTRACT.md#programmatic-api) — short SDK pitch in the v1-stable contract doc
+- [JSON_CONTRACT.md Response statuses](./JSON_CONTRACT.md#response-statuses) — full status catalog
+- [JSON_CONTRACT.md Hints flow](./JSON_CONTRACT.md#hints-flow) — hint vocabulary and shapes
+- [JSON_CONTRACT.md Error codes](./JSON_CONTRACT.md#error-codes) — error.code table
+- [JSON_CONTRACT.md Recommended automation flow](./JSON_CONTRACT.md#recommended-automation-flow) — CLI-side equivalent of the SDK pattern above

drizzle-kit/scripts/build.ts

@@ -89,11 +89,17 @@ async function buildCli() {
 	console.log('  Built bin.cjs');
 }
 
+// tsdown's `emitDtsOnly: true` still emits chunked .js files alongside the
+// declarations. If tsdown writes to ./dist it overwrites rolldown's clean
+// single-file bundles and produces a CJS entry that fails to load. Direct
+// tsdown's output at a temp dir and copy only .d.ts / .d.mts back into ./dist.
+const TSDOWN_TEMP_DIR = './dist/__dts-temp';
+
 async function buildDeclarations() {
 	// Use tsdown for declaration bundling - it handles path resolution and creates bundled .d.ts files
 	await tsdown({
 		entry: ['./src/index.ts'],
-		outDir: './dist',
+		outDir: TSDOWN_TEMP_DIR,
 		external: [...driversPackages, /^drizzle-orm\/?/],
 		dts: { emitDtsOnly: true },
 		format: ['cjs', 'es'],
@@ -109,7 +115,7 @@ async function buildDeclarations() {
 
 	await tsdown({
 		entry: ['./src/ext/api-postgres.ts', './src/ext/api-mysql.ts', './src/ext/api-sqlite.ts'],
-		outDir: './dist',
+		outDir: TSDOWN_TEMP_DIR,
 		external: ['esbuild', 'drizzle-orm', ...driversPackages, /^drizzle-orm\/?/],
 		dts: { emitDtsOnly: true },
 		format: ['cjs', 'es'],
@@ -126,6 +132,16 @@ async function buildDeclarations() {
 	console.log('  Built declarations');
 }
 
+async function copyDeclarationsAndCleanTemp() {
+	const entries = await fs.readdir(TSDOWN_TEMP_DIR);
+	await Promise.all(
+		entries
+			.filter((f) => f.endsWith('.d.ts') || f.endsWith('.d.mts'))
+			.map((f) => fs.copyFile(`${TSDOWN_TEMP_DIR}/${f}`, `dist/${f}`)),
+	);
+	rmSync(TSDOWN_TEMP_DIR, { recursive: true, force: true });
+}
+
 async function postProcessApiFiles() {
 	const apiFiles = ['dist/api-postgres.js', 'dist/api-mysql.js', 'dist/api-sqlite.js'];
 	await Promise.all(
@@ -195,6 +211,7 @@ async function main() {
 		buildDeclarations(),
 	]);
 
+	await copyDeclarationsAndCleanTemp();
 	await Promise.all([
 		postProcessApiFiles(),
 		fs.copyFile('package.json', 'dist/package.json'),

drizzle-kit/src/cli/commands/check.ts

@@ -1,7 +1,7 @@
 import chalk from 'chalk';
 import { readFileSync } from 'fs';
-import { getCommutativityDialect } from 'src/commutativity';
-import type { MigrationNode, NonCommutativityReport, UnifiedBranchConflict } from 'src/commutativity/types';
+import { getCommutativityDialect } from '../../commutativity';
+import type { MigrationNode, NonCommutativityReport, UnifiedBranchConflict } from '../../commutativity/types';
 import type { Dialect } from '../../utils/schemaValidator';
 import { prepareOutFolder, validatorForDialect } from '../../utils/utils-node';
 import { CheckCliError } from '../errors';

drizzle-kit/src/cli/commands/generate-cockroach.ts

@@ -1,5 +1,3 @@
-import { fromDrizzleSchema, prepareFromSchemaFiles } from 'src/dialects/cockroach/drizzle';
-import { prepareOutFolder } from 'src/utils/utils-node';
 import type {
 	CheckConstraint,
 	CockroachEntities,
@@ -15,17 +13,13 @@ import type {
 } from '../../dialects/cockroach/ddl';
 import { createDDL, interimToDDL } from '../../dialects/cockroach/ddl';
 import { ddlDiff, ddlDiffDry } from '../../dialects/cockroach/diff';
+import { fromDrizzleSchema, prepareFromSchemaFiles } from '../../dialects/cockroach/drizzle';
 import { prepareSnapshot } from '../../dialects/cockroach/serializer';
+import { prepareOutFolder } from '../../utils/utils-node';
 import { isJsonMode } from '../context';
+import { CommandOutputCliError } from '../errors';
 import { resolver } from '../prompts';
-import {
-	cockroachSchemaError,
-	cockroachSchemaWarning,
-	explain,
-	explainJsonOutput,
-	humanLog,
-	printJsonOutput,
-} from '../views';
+import { cockroachSchemaError, cockroachSchemaWarning, explain, explainJsonOutput, humanLog } from '../views';
 import { writeResult } from './generate-common';
 import type { ExportConfig, GenerateConfig } from './utils';
 
@@ -36,7 +30,7 @@ export const handle = async (config: GenerateConfig) => {
 	const { snapshots } = prepareOutFolder(outFolder);
 	const { ddlCur, ddlPrev, snapshot, custom } = await prepareSnapshot(snapshots, filenames);
 	if (config.custom) {
-		writeResult({
+		return writeResult({
 			snapshot: custom,
 			sqlStatements: [],
 			outFolder,
@@ -47,7 +41,6 @@ export const handle = async (config: GenerateConfig) => {
 			renames: [],
 			snapshots,
 		});
-		return;
 	}
 
 	const { sqlStatements, renames, groupedStatements, statements } = await ddlDiff(
@@ -68,11 +61,11 @@ export const handle = async (config: GenerateConfig) => {
 	);
 
 	if (json && config.hints.hasMissingHints()) {
-		config.hints.emitAndExit();
+		return config.hints.toResponse();
 	}
 
 	if (!config.explain) {
-		writeResult({
+		return writeResult({
 			snapshot: snapshot,
 			sqlStatements,
 			outFolder,
@@ -82,22 +75,21 @@ export const handle = async (config: GenerateConfig) => {
 			renames,
 			snapshots,
 		});
-		return;
 	}
 
 	if (json) {
 		if (sqlStatements.length === 0) {
-			printJsonOutput({ status: 'no_changes', dialect: 'cockroach' });
-			return;
+			return { status: 'no_changes' as const, dialect: 'cockroach' };
 		}
-		printJsonOutput(explainJsonOutput('cockroach', statements, []));
-		return;
+		return explainJsonOutput('cockroach', statements, []);
 	}
 
 	const explainMessage = explain('cockroach', groupedStatements, []);
 	if (explainMessage) {
 		humanLog(explainMessage);
 	}
+
+	return { status: 'ok' as const, dialect: 'cockroach' };
 };
 
 export const handleExport = async (config: ExportConfig) => {
@@ -112,15 +104,19 @@ export const handleExport = async (config: ExportConfig) => {
 	}
 
 	if (errors.length > 0) {
-		console.log(errors.map((it) => cockroachSchemaError(it)).join('\n'));
-		process.exit(1);
+		throw new CommandOutputCliError('generate', errors.map((it) => cockroachSchemaError(it)).join('\n'), {
+			stage: 'schema',
+			dialect: 'cockroach',
+		});
 	}
 
 	const { ddl, errors: errors2 } = interimToDDL(schema);
 
 	if (errors2.length > 0) {
-		console.log(errors2.map((it) => cockroachSchemaError(it)).join('\n'));
-		process.exit(1);
+		throw new CommandOutputCliError('generate', errors2.map((it) => cockroachSchemaError(it)).join('\n'), {
+			stage: 'ddl',
+			dialect: 'cockroach',
+		});
 	}
 
 	const { sqlStatements } = await ddlDiffDry(createDDL(), ddl, 'default');