Add machine-readable output modes (--output text|json), a typed SDK, and agent skills to drizzle-kit

[dankochetov]

Summary

Gives drizzle-kit generate / push a machine-readable, non-interactive contract so agents, build tools, and CI can drive them without scraping prompts or terminal output. The old single --json boolean is replaced by three orthogonal axes:

• Output format — --output text (human, default) vs --output json (one machine-readable envelope), controls how results render.
• Interactivity — whether the CLI may prompt, derived purely from the terminal: interactive = output === 'text' && !!process.stdin.isTTY. --output json is therefore always non-interactive.
• Hints — --hints / --hints-file supply rename/data-loss decisions up front so the CLI never has to ask, in either output mode.

Three surfaces ship together: the --output CLI, a typed root-level SDK, and an installable Agent Skills catalog.

What's included

1. --output text | json for generate and push

--output json emits a single JSON object on stdout, a discriminated union keyed on status:

• ok — work succeeded (migration_path for generate; statements / hints in --explain)
• no_changes — schema in sync, nothing to do
• missing_hints — the diff has ambiguous or unsafe operations that need caller input; the response lists unresolved items (exit code 2)
• error — structured failure with a stable error.code

Under the default --output text, the same run is human-readable. When it is non-interactive (non-TTY) and a decision is still unresolved, it prints a missing-decisions report to stdout and exits 2 instead of hanging on a prompt. Full envelope / status / error-code reference: drizzle-kit/JSON_CONTRACT.md; the text/interactivity model and the report shape: drizzle-kit/OUTPUT_MODES.md.

2. Hints flow (output-agnostic)

Ambiguous diffs (rename vs. create+drop) and unsafe operations surface as typed unresolved items the caller resolves and resubmits — identically in text and JSON mode. Kinds:

• rename_or_create
• confirm_data_loss — table, column, schema, view, primary_key, add_not_null, add_unique (each carries a reason: non_empty, nulls_present, duplicates_present, type_change)
• structural errors via unsupported_schema_change — drop_pk_dependency, fk_target_not_unique, rename_blocked_by_check_constraint, rename_schema_unsupported

Implemented for postgres, mysql, sqlite, mssql, cockroach, and singlestore. The full vocabulary (kinds, reasons, identifier-tuple shapes) lives in drizzle-kit/HINTS.md.

3. SDK — typed root-level exports

The same contract is callable as a TypeScript API:

import { generate, push, defineConfig } from 'drizzle-kit';
import type { Config, GenerateOptions, PushOptions, Hint, MissingHint } from 'drizzle-kit';

const res = await generate({ dialect: 'postgresql', schema: './src/schema.ts', out: './drizzle' });
if (res.status === 'missing_hints') {
  // res.unresolved: MissingHint[] — build a Hint[] reply and re-invoke
  await generate({ dialect: 'postgresql', schema: './src/schema.ts', out: './drizzle', hints });
}

The SDK always runs in JSON mode internally (no --output flag at the call site) and returns the same envelope the CLI prints. hints is a raw Hint[] (the CLI --hints flag is the JSON-string form); push credentials are passed flat (url / host / …), with no dbCredentials wrapper. Response shapes are obtained via Awaited<ReturnType<typeof generate | push>> and narrowed on status — they are not separate named exports. Full surface in drizzle-kit/SDK.md.

4. Agent Skills catalog (drizzle-kit skills)

npx drizzle-kit skills installs a bundled Agent Skills catalog into the host project — .claude/skills/<slug>/SKILL.md for Claude Code, .agents/skills/<slug>/SKILL.md for Codex / Cursor / Gemini CLI / Cline / Copilot and any tool following the open AGENTS.md convention. Skills shipped:

• drizzle — umbrella staleness check against the installed drizzle-kit
• drizzle-generate, drizzle-push, drizzle-migrations — the command workflows
• drizzle-hints — resolving missing_hints
• drizzle-responses-and-errors — decoding the envelope and error codes
• drizzle-output-modes — choosing --output text vs json, interactivity, and the text report

Documentation

• drizzle-kit/JSON_CONTRACT.md — the JSON-mode envelope (statuses, error codes) (new)
• drizzle-kit/OUTPUT_MODES.md — the --output text | json and interactivity model + missing-decisions text report (new)
• drizzle-kit/HINTS.md — the output-agnostic hint vocabulary (new)
• drizzle-kit/SDK.md — the programmatic SDK surface (new)

Compatibility

• Interactive CLI behavior is unchanged — --output text is the default and prompts on a TTY exactly as before.
• No changes to the snapshot format or migration SQL output.