@drzl/cli 4.21.0 → 4.23.0

package/dist/cli.js

@@ -1,28 +1,290 @@
 #!/usr/bin/env node
 import {
+  CONFIG_FILE_NAMES,
+  ConfigValidationError,
+  GENERATOR_KINDS,
   addressableName,
   ambiguousPatternWarnings,
   computeGeneratorOutputDirs,
   computeWatchTargets,
+  configFromKinds,
   displayTableName,
+  expressOutDir,
+  fastifyOutDir,
   filterTables,
+  graphqlOutDir,
   hasNamedSchemas,
+  honoOutDir,
+  importFreshConfigModule,
   loadConfig,
   matchesAny,
   matchesTable,
+  nearestKey,
+  nestjsOutDir,
+  tableAliases,
   tableFilterWarnings,
   trpcOutDir
-} from "./chunk-XNNKHBGV.js";
+} from "./chunk-54E2IO7N.js";
 
 // src/cli.ts
-import { SchemaAnalyzer } from "@drzl/analyzer";
-import { ORPCGenerator } from "@drzl/generator-orpc";
-import chalk3 from "chalk";
+import { qualifiedTableName as qualifiedTableName2, SchemaAnalyzer as SchemaAnalyzer2 } from "@drzl/analyzer";
 import chokidar from "chokidar";
-import cliProgress from "cli-progress";
 import { Command } from "commander";
-import * as path4 from "path";
+import * as path7 from "path";
+
+// src/output.ts
+import { Chalk } from "chalk";
+import cliProgress from "cli-progress";
 import ora from "ora";
+var EXIT_OK = 0;
+var EXIT_FAILED = 1;
+var EXIT_FINDINGS = 2;
+var PROGRESS_MIN_TABLES = 25;
+function colorLevelFor(stream, env) {
+  if (env.NO_COLOR !== void 0 && env.NO_COLOR !== "") return 0;
+  if (env.TERM === "dumb") return 0;
+  const forced = env.FORCE_COLOR;
+  if (forced !== void 0) {
+    if (forced === "false" || forced === "0") return 0;
+    if (forced === "" || forced === "true") return 1;
+    const n = Number.parseInt(forced, 10);
+    if (Number.isInteger(n)) return Math.min(Math.max(n, 0), 3);
+    return 1;
+  }
+  if (!stream.isTTY) return 0;
+  if (env.COLORTERM === "truecolor" || env.COLORTERM === "24bit") return 3;
+  if (env.TERM?.includes("256")) return 2;
+  return 1;
+}
+function shouldShowProgress(opts) {
+  if (opts.quiet || opts.json) return false;
+  if (!opts.stderr.isTTY) return false;
+  return opts.tables >= PROGRESS_MIN_TABLES;
+}
+function createProgress(enabled, total, stream) {
+  if (!enabled) {
+    return { start() {
+    }, update() {
+    }, stop() {
+    } };
+  }
+  const bar = new cliProgress.SingleBar(
+    { hideCursor: true, stream },
+    cliProgress.Presets.shades_classic
+  );
+  let running = false;
+  return {
+    start() {
+      if (running) return;
+      bar.start(total, 0);
+      running = true;
+    },
+    update(value) {
+      if (running) bar.update(value);
+    },
+    stop() {
+      if (!running) return;
+      bar.stop();
+      running = false;
+    }
+  };
+}
+var Output = class {
+  constructor(options = {}) {
+    this.stdout = options.stdout ?? process.stdout;
+    this.stderr = options.stderr ?? process.stderr;
+    this.env = options.env ?? process.env;
+    this.quiet = options.quiet ?? false;
+    this.json = options.json ?? false;
+    this.outStyle = new Chalk({ level: colorLevelFor(this.stdout, this.env) });
+    this.errStyle = new Chalk({ level: colorLevelFor(this.stderr, this.env) });
+  }
+  /** The command's answer. Never suppressed by `--quiet`, because then nothing would be left. */
+  data(text) {
+    this.stdout.write(text.endsWith("\n") ? text : text + "\n");
+  }
+  /**
+   * The one JSON document `--json` promises, and the reason nothing else may touch stdout.
+   *
+   * Stringified without indentation on purpose: this is a machine's copy, `jq` formats it for a
+   * human, and the two commands that already print an indented document (`analyze`, `doctor`) keep
+   * doing so through `data` because their shape is a published contract.
+   */
+  jsonData(payload) {
+    this.data(JSON.stringify(payload));
+  }
+  /** Narration. Dropped by `--quiet` and by `--json`. */
+  note(text) {
+    if (this.quiet || this.json) return;
+    this.stderr.write(text + "\n");
+  }
+  /** A warning: narration a user asked to be quiet still does not need. */
+  warn(text) {
+    if (this.quiet || this.json) return;
+    this.stderr.write(this.errStyle.yellow(text) + "\n");
+  }
+  /**
+   * A failure. Never suppressed by anything, because a script that cannot tell a success from a
+   * swallowed failure is worse off than one with no `--quiet` at all.
+   *
+   * Under `--json` the machine-readable failure goes to stdout as the document, so this stays
+   * quiet there rather than printing the same fact twice in two shapes.
+   */
+  error(text, detail) {
+    if (this.json) return;
+    const line = this.errStyle.red(text) + (detail ? " " + detail : "");
+    this.stderr.write(line + "\n");
+  }
+  /** A hint under an error. Suppressed by `--quiet`: the error above it already said what broke. */
+  hint(text) {
+    if (this.quiet || this.json) return;
+    this.stderr.write(this.errStyle.dim(text) + "\n");
+  }
+  /**
+   * A spinner on stderr, or nothing.
+   *
+   * `ora` is constructed only when stderr is a terminal. Given a pipe it still writes its text
+   * once as `- Analyzing...`, which is a line nobody reading a log wants, and given `NO_COLOR` it
+   * writes a coloured symbol anyway. Both are avoided by not building it.
+   */
+  spinner(text) {
+    const live = !this.quiet && !this.json && this.stderr.isTTY ? ora({
+      text,
+      stream: this.stderr,
+      // ora paints its own frame cyan through its own chalk, which is a second colour
+      // decision beside this one and does not read `NO_COLOR` either. Measured with the
+      // variable set: everything else on the line went plain and the spinner frame arrived
+      // as `[36m⠋[39m`. `false` is ora's documented way to turn that off.
+      color: this.errStyle.level > 0 ? "cyan" : false
+    }).start() : null;
+    return {
+      succeed: (done) => {
+        live?.stop();
+        this.succeed(done);
+      },
+      fail: (done) => {
+        live?.stop();
+        this.error(done);
+      },
+      stop: () => live?.stop()
+    };
+  }
+  /**
+   * A completed step.
+   *
+   * The tick is rendered here rather than by `ora.succeed`, which is the fix for the escape that
+   * reached piped output: `log-symbols` colours the symbol from the environment alone and never
+   * looks at the stream, so `drzl analyze 2> log` used to write `✔` into
+   * the file. Here the symbol goes through the same per-stream decision as everything else.
+   */
+  succeed(text) {
+    if (this.quiet || this.json) return;
+    this.stderr.write(this.errStyle.green("\u2714") + " " + text + "\n");
+  }
+  /** A progress bar for `tables` items, or a no-op. See `shouldShowProgress` for the four gates. */
+  progress(tables) {
+    return createProgress(
+      shouldShowProgress({
+        tables,
+        stderr: this.stderr,
+        quiet: this.quiet,
+        json: this.json
+      }),
+      tables,
+      this.stderr
+    );
+  }
+  /**
+   * Whether an unrequested extra, such as the sponsor tip, should be shown at all.
+   *
+   * A terminal is the only place an aside has a reader. Piped into a file it is noise in someone's
+   * log, and under `--json` it would be noise in the middle of a document.
+   */
+  get wantsAsides() {
+    return !this.quiet && !this.json && Boolean(this.stderr.isTTY);
+  }
+};
+function jsonFailure(command, code, message, exitCode = EXIT_FAILED) {
+  return { ok: false, command, code, message, exitCode };
+}
+function messageOf(value) {
+  const message = value?.message;
+  return String(message ?? value);
+}
+
+// src/express-options.ts
+function expressOptions(g, cfg) {
+  return {
+    outputDir: expressOutDir(g, cfg),
+    includeRelations: g.includeRelations,
+    naming: g.naming,
+    outputHeader: g.outputHeader,
+    format: g.format,
+    importExtension: g.importExtension,
+    validation: g.validation
+  };
+}
+
+// src/fastify-options.ts
+function fastifyOptions(g, cfg) {
+  return {
+    outputDir: fastifyOutDir(g, cfg),
+    includeRelations: g.includeRelations,
+    naming: g.naming,
+    outputHeader: g.outputHeader,
+    format: g.format,
+    importExtension: g.importExtension
+  };
+}
+
+// src/generator-loader.ts
+var GeneratorNotInstalledError = class extends Error {
+  constructor(specifier, reason) {
+    super(`${specifier} is not installed`);
+    this.specifier = specifier;
+    this.reason = reason;
+    this.name = "GeneratorNotInstalledError";
+  }
+};
+function isPackageMissing(err, specifier) {
+  const code = err?.code;
+  if (code !== "ERR_MODULE_NOT_FOUND") return false;
+  const message = err?.message;
+  return typeof message === "string" && message.includes(`'${specifier}'`);
+}
+async function loadGenerator(specifier, load) {
+  try {
+    return await load();
+  } catch (e) {
+    if (isPackageMissing(e, specifier)) throw new GeneratorNotInstalledError(specifier, e);
+    throw e;
+  }
+}
+
+// src/graphql-options.ts
+function graphqlOptions(g, cfg) {
+  return {
+    outputDir: graphqlOutDir(g, cfg),
+    naming: g.naming,
+    outputHeader: g.outputHeader,
+    format: g.format,
+    importExtension: g.importExtension
+  };
+}
+
+// src/hono-options.ts
+function honoOptions(g, cfg) {
+  return {
+    outputDir: honoOutDir(g, cfg),
+    includeRelations: g.includeRelations,
+    naming: g.naming,
+    validator: g.validator,
+    outputHeader: g.outputHeader,
+    format: g.format,
+    importExtension: g.importExtension,
+    validation: g.validation
+  };
+}
 
 // src/validation-options.ts
 function validationOptions(g, cfg, outDir, caps = {}) {
@@ -53,7 +315,8 @@ function validationOptions(g, cfg, outDir, caps = {}) {
       typedColumns: g.typedColumns
     } : {},
     ...caps.standardSchema ? { standardSchema: g.standardSchema } : {},
-    ...caps.meta ? { meta: g.meta } : {}
+    ...caps.meta ? { meta: g.meta } : {},
+    ...caps.constraints ? { constraints: g.constraints } : {}
   };
 }
 
@@ -67,7 +330,57 @@ function jsonSchemaOptions(g, cfg, outDir) {
     document: g.document,
     // Read only while emitting a document, where it adds `/users/{id}/posts`. The per-table
     // schemas are flat whatever it says.
-    includeRelations: g.includeRelations
+    includeRelations: g.includeRelations,
+    // The mirror image: read only for the per-table modules, since the document shares regardless.
+    sharedEnums: g.sharedEnums
+  };
+}
+
+// src/nestjs-options.ts
+function nestjsOptions(g, cfg) {
+  return {
+    outputDir: nestjsOutDir(g, cfg),
+    naming: g.naming,
+    outputHeader: g.outputHeader,
+    format: g.format,
+    importExtension: g.importExtension,
+    validation: g.validation
+  };
+}
+
+// src/orpc-options.ts
+function orpcOptions(g, cfg, servicesDir) {
+  return {
+    outputDir: cfg.outDir,
+    template: g.template,
+    includeRelations: g.includeRelations,
+    naming: g.naming,
+    outputHeader: g.outputHeader,
+    format: g.format,
+    templateOptions: g.templateOptions,
+    importExtension: g.importExtension,
+    validation: g.validation,
+    // Documented on this generator since it was added and unreachable from a config file for most
+    // of that time, because the config schema had no such key and zod stripped it in silence.
+    databaseInjection: g.databaseInjection,
+    // Where the service generator is actually writing, so a router template that imports services
+    // spells a path that exists. The templates default this to `src/services`, which is right only
+    // by coincidence for a config that puts them elsewhere.
+    servicesDir
+  };
+}
+
+// src/service-options.ts
+function serviceOptions(g, outDir) {
+  return {
+    outDir,
+    outputHeader: g.outputHeader,
+    format: g.format,
+    dataAccess: g.dataAccess,
+    dbImportPath: g.dbImportPath,
+    schemaImportPath: g.schemaImportPath,
+    importExtension: g.importExtension,
+    databaseInjection: g.databaseInjection
   };
 }
 
@@ -90,18 +403,335 @@ function trpcOptions(g, cfg, servicesDir) {
   };
 }
 
+// src/generator-registry.ts
+var VALIDATOR_DEFAULT_DIRS = {
+  zod: "src/validators/zod",
+  valibot: "src/validators/valibot",
+  arktype: "src/validators/arktype",
+  typebox: "src/validators/typebox",
+  effect: "src/validators/effect",
+  "json-schema": "src/validators/json-schema"
+};
+var SERVICES_DEFAULT_DIR = "src/services";
+function resolveServicesDir(cfg) {
+  return cfg.generators.find((g) => g.kind === "service")?.path ?? SERVICES_DEFAULT_DIR;
+}
+var GENERATORS = [
+  {
+    kind: "orpc",
+    specifier: "@drzl/generator-orpc",
+    load: () => import("@drzl/generator-orpc"),
+    construct: (m, analysis) => new m.ORPCGenerator(analysis),
+    // `cfg.outDir` and never `g.path`: see `orpcOptions` for why that is this generator's own
+    // arrangement rather than an oversight to correct here.
+    outputDir: (_g, cfg) => cfg.outDir,
+    options: (g, cfg, ctx) => orpcOptions(g, cfg, ctx.servicesDir)
+  },
+  {
+    kind: "trpc",
+    // An optional dependency, like seven others below. A package that has never been published
+    // cannot publish through npm's trusted-publisher OIDC flow, so its first version has to go out
+    // by hand, and naming it as a hard dependency of the CLI in the same release breaks
+    // `npm i @drzl/cli` for everyone until it exists. A missing optional dependency is skipped by
+    // the installer rather than failing it, which is why these really can be absent on an ordinary
+    // install, and why `loadGenerator` tells absence apart from failure.
+    specifier: "@drzl/generator-trpc",
+    load: () => import("./dist-ZIHNXQ7U.js"),
+    construct: (m, analysis) => new m.TRPCGenerator(analysis),
+    outputDir: (g, cfg) => trpcOutDir(g, cfg),
+    options: (g, cfg, ctx) => trpcOptions(g, cfg, ctx.servicesDir)
+  },
+  {
+    kind: "hono",
+    specifier: "@drzl/generator-hono",
+    load: () => import("./dist-P24ILO5N.js"),
+    construct: (m, analysis) => new m.HonoGenerator(analysis),
+    outputDir: (g, cfg) => honoOutDir(g, cfg),
+    options: (g, cfg) => honoOptions(g, cfg)
+  },
+  {
+    kind: "express",
+    specifier: "@drzl/generator-express",
+    load: () => import("./dist-T5376MW7.js"),
+    construct: (m, analysis) => new m.ExpressGenerator(analysis),
+    outputDir: (g, cfg) => expressOutDir(g, cfg),
+    options: (g, cfg) => expressOptions(g, cfg)
+  },
+  {
+    kind: "fastify",
+    specifier: "@drzl/generator-fastify",
+    load: () => import("./dist-KQMPKOFK.js"),
+    construct: (m, analysis) => new m.FastifyGenerator(analysis),
+    outputDir: (g, cfg) => fastifyOutDir(g, cfg),
+    options: (g, cfg) => fastifyOptions(g, cfg)
+  },
+  {
+    kind: "nestjs",
+    specifier: "@drzl/generator-nestjs",
+    load: () => import("./dist-SGI2I53L.js"),
+    construct: (m, analysis) => new m.NestJSGenerator(analysis),
+    outputDir: (g, cfg) => nestjsOutDir(g, cfg),
+    options: (g, cfg) => nestjsOptions(g, cfg)
+  },
+  {
+    kind: "graphql",
+    specifier: "@drzl/generator-graphql",
+    load: () => import("./dist-UVP6B4XJ.js"),
+    construct: (m, analysis) => new m.GraphQLGenerator(analysis),
+    outputDir: (g, cfg) => graphqlOutDir(g, cfg),
+    options: (g, cfg) => graphqlOptions(g, cfg)
+  },
+  {
+    kind: "service",
+    specifier: "@drzl/generator-service",
+    load: () => import("@drzl/generator-service"),
+    construct: (m, analysis) => new m.ServiceGenerator(analysis),
+    outputDir: (g) => g.path ?? SERVICES_DEFAULT_DIR,
+    options: (g, _cfg, ctx) => serviceOptions(g, ctx.outDir)
+  },
+  {
+    kind: "zod",
+    specifier: "@drzl/generator-zod",
+    load: () => import("@drzl/generator-zod"),
+    construct: (m, analysis) => new m.ZodGenerator(analysis),
+    outputDir: (g) => g.path ?? VALIDATOR_DEFAULT_DIRS.zod,
+    // `meta` is zod-only; see `GeneratorCapabilities.meta` for why it is not passed to the other
+    // four rather than being passed and ignored.
+    options: (g, cfg, ctx) => validationOptions(g, cfg, ctx.outDir, {
+      schemaTypes: true,
+      meta: true,
+      constraints: true
+    })
+  },
+  {
+    kind: "valibot",
+    specifier: "@drzl/generator-valibot",
+    load: () => import("@drzl/generator-valibot"),
+    construct: (m, analysis) => new m.ValibotGenerator(analysis),
+    outputDir: (g) => g.path ?? VALIDATOR_DEFAULT_DIRS.valibot,
+    options: (g, cfg, ctx) => validationOptions(g, cfg, ctx.outDir, { schemaTypes: true, constraints: true })
+  },
+  {
+    kind: "arktype",
+    specifier: "@drzl/generator-arktype",
+    load: () => import("@drzl/generator-arktype"),
+    construct: (m, analysis) => new m.ArkTypeGenerator(analysis),
+    outputDir: (g) => g.path ?? VALIDATOR_DEFAULT_DIRS.arktype,
+    options: (g, cfg, ctx) => validationOptions(g, cfg, ctx.outDir, { schemaTypes: false })
+  },
+  {
+    kind: "typebox",
+    specifier: "@drzl/generator-typebox",
+    load: () => import("@drzl/generator-typebox"),
+    construct: (m, analysis) => new m.TypeBoxGenerator(analysis),
+    outputDir: (g) => g.path ?? VALIDATOR_DEFAULT_DIRS.typebox,
+    options: (g, cfg, ctx) => validationOptions(g, cfg, ctx.outDir, { schemaTypes: true, standardSchema: true })
+  },
+  {
+    kind: "effect",
+    specifier: "@drzl/generator-effect",
+    load: () => import("./dist-KX62ETKK.js"),
+    construct: (m, analysis) => new m.EffectGenerator(analysis),
+    outputDir: (g) => g.path ?? VALIDATOR_DEFAULT_DIRS.effect,
+    options: (g, cfg, ctx) => validationOptions(g, cfg, ctx.outDir, { schemaTypes: true })
+  },
+  {
+    kind: "json-schema",
+    specifier: "@drzl/generator-json-schema",
+    load: () => import("./dist-QYH7DRFY.js"),
+    construct: (m, analysis) => new m.JsonSchemaGenerator(analysis),
+    outputDir: (g) => g.path ?? VALIDATOR_DEFAULT_DIRS["json-schema"],
+    options: (g, cfg, ctx) => jsonSchemaOptions(g, cfg, ctx.outDir)
+  }
+];
+var GENERATOR_BY_KIND = new Map(
+  GENERATORS.map((entry) => [entry.kind, entry])
+);
+function entryFor(kind) {
+  const entry = GENERATOR_BY_KIND.get(kind);
+  if (!entry) throw new Error(`No generator is registered for kind "${kind}".`);
+  return entry;
+}
+function filesOf(result) {
+  return Array.isArray(result) ? result : result.files;
+}
+async function runGenerator(entry, g, cfg, ctx) {
+  return runGeneratorWithOptions(entry, ctx.analysis, {
+    ...entry.options(g, cfg, {
+      outDir: entry.outputDir(g, cfg),
+      servicesDir: ctx.servicesDir
+    }),
+    ...ctx.fileSink ? { fileSink: ctx.fileSink } : {},
+    ...ctx.onProgress ? { onProgress: ctx.onProgress } : {}
+  });
+}
+async function runGeneratorWithOptions(entry, analysis, options) {
+  const module = await loadGenerator(entry.specifier, entry.load);
+  return filesOf(await entry.construct(module, analysis).generate(options));
+}
+
+// src/kind-selection.ts
+var PIPELINE_PREFIX = "generate-";
+var KindSelectionError = class extends Error {
+  constructor(code, message, hint) {
+    super(message);
+    this.code = code;
+    this.hint = hint;
+    this.name = "KindSelectionError";
+  }
+};
+function kindList() {
+  return GENERATOR_KINDS.join(", ");
+}
+function isKind(value) {
+  return GENERATOR_KINDS.includes(value);
+}
+function parseOnly(value, flag = "--only") {
+  if (value === void 0 || value === null) return void 0;
+  const requested = String(value).split(",").map((part) => part.trim()).filter(Boolean);
+  if (!requested.length) {
+    throw new KindSelectionError(
+      "DRZL_CLI_ONLY",
+      `${flag} was given no kind. Pass one or more of: ${kindList()}.`
+    );
+  }
+  const kinds = /* @__PURE__ */ new Set();
+  for (const name of requested) {
+    if (isKind(name)) {
+      kinds.add(name);
+      continue;
+    }
+    const bare = name.startsWith(PIPELINE_PREFIX) ? name.slice(PIPELINE_PREFIX.length) : "";
+    throw new KindSelectionError(
+      "DRZL_CLI_ONLY",
+      `${flag}: there is no generator kind "${name}".`,
+      isKind(bare) ? `Write it the way the config does: ${flag} ${bare}.` : `Valid kinds are: ${kindList()}.`
+    );
+  }
+  return kinds;
+}
+function resolveWatchSelection(opts) {
+  const only = parseOnly(opts.only);
+  const pipeline = opts.pipeline === void 0 || opts.pipeline === null ? "all" : String(opts.pipeline);
+  if (pipeline === "analyze") {
+    if (only) {
+      throw new KindSelectionError(
+        "DRZL_CLI_ONLY",
+        "--pipeline analyze runs no generator, so it cannot be combined with --only.",
+        "Drop one of the two."
+      );
+    }
+    return { analyzeOnly: true };
+  }
+  if (pipeline === "all") return { analyzeOnly: false, kinds: only };
+  if (only) {
+    throw new KindSelectionError(
+      "DRZL_CLI_ONLY",
+      "--pipeline and --only say the same thing, so passing both is ambiguous.",
+      `Use --only ${[...only].join(",")} on its own; --pipeline is the older spelling.`
+    );
+  }
+  const bare = pipeline.startsWith(PIPELINE_PREFIX) ? pipeline.slice(PIPELINE_PREFIX.length) : "";
+  if (!isKind(bare)) {
+    throw new KindSelectionError(
+      "DRZL_CLI_ONLY",
+      `--pipeline: there is no pipeline called "${pipeline}".`,
+      // A bare kind is the mirror image of the mistake `parseOnly` names, and the answer is the
+      // flag that takes bare kinds rather than the list of sixteen values this one takes.
+      isKind(pipeline) ? `That is a generator kind, so it goes to the newer flag: --only ${pipeline}.` : `Use --only <kind>, or one of: all, analyze, ${GENERATOR_KINDS.map(
+        (k) => PIPELINE_PREFIX + k
+      ).join(", ")}.`
+    );
+  }
+  return { analyzeOnly: false, kinds: /* @__PURE__ */ new Set([bare]) };
+}
+function selectGenerators(generators, kinds) {
+  if (!kinds) return [...generators];
+  return generators.filter((g) => kinds.has(g.kind));
+}
+function emptySelectionMessage(kinds, configured, flag = "--only") {
+  if (!kinds || selectGenerators(configured, kinds).length) return void 0;
+  const asked = [...kinds].join(", ");
+  const names = [...new Set(configured.map((g) => g.kind))];
+  return `${flag} ${asked} matched no generator in this config, which names: ${names.join(", ") || "none"}.`;
+}
+
+// src/schema-outcome.ts
+var SCHEMA_UNREADABLE_CODE = "DRZL_SCHEMA_001";
+var SCHEMA_EMPTY_CODE = "DRZL_SCHEMA_002";
+var SCHEMA_FILTERED_CODE = "DRZL_SCHEMA_003";
+var NOTHING_GENERATED = "Nothing was generated.";
+var UNREADABLE_CODES = /* @__PURE__ */ new Set(["DRZL_ANL_NOFILE", "DRZL_ANL_IMPORT"]);
+function firstLine(message) {
+  return String(message).split("\n")[0].trim();
+}
+function describeSchemaTarget(schema) {
+  if (typeof schema === "string") return schema;
+  if (schema.length === 1) return schema[0];
+  return `${schema.length} schema files`;
+}
+function schemaLoadFailure(issues, schema, consequence = NOTHING_GENERATED) {
+  const blocking = issues.filter(
+    (issue) => issue.level === "error" && issue.code && UNREADABLE_CODES.has(issue.code)
+  );
+  if (!blocking.length) return void 0;
+  const first = blocking[0];
+  const more = blocking.length > 1 ? ` (and ${blocking.length - 1} more)` : "";
+  const single = typeof schema === "string" ? schema : schema.length === 1 ? schema[0] : void 0;
+  if (first.code === "DRZL_ANL_NOFILE") {
+    const named = single ?? afterPrefix(first.message, "Schema file not found:");
+    return {
+      code: SCHEMA_UNREADABLE_CODE,
+      message: `Schema file not found (${SCHEMA_UNREADABLE_CODE}): ${named}${more}`,
+      hint: 'Check the "schema" path in your drzl config, or point --config at another one. ' + consequence
+    };
+  }
+  const reason = single ? firstLine(afterPrefix(first.message, "Failed to import schema:")) : firstLine(String(first.message ?? ""));
+  const message = single ? `Could not load the schema module ${single} (${SCHEMA_UNREADABLE_CODE}): ${reason}${more}` : `Could not load a schema module (${SCHEMA_UNREADABLE_CODE}): ${reason}${more}`;
+  return {
+    code: SCHEMA_UNREADABLE_CODE,
+    message,
+    hint: single ? `Fix that error and run again. \`drzl analyze ${single}\` prints it in full. ${consequence}` : `Fix that error and run again. ${consequence}`
+  };
+}
+function afterPrefix(message, prefix) {
+  const text = String(message ?? "");
+  return text.startsWith(prefix) ? text.slice(prefix.length).trim() : text;
+}
+function nothingToGenerate(opts) {
+  if (opts.remaining.length > 0) return void 0;
+  const target = describeSchemaTarget(opts.schema);
+  const consequence = opts.consequence ?? NOTHING_GENERATED;
+  if (!opts.analyzed.length) {
+    return {
+      code: SCHEMA_EMPTY_CODE,
+      message: `No Drizzle tables found in ${target} (${SCHEMA_EMPTY_CODE}).`,
+      hint: "That module imported cleanly and exported no tables, so every generator would write an empty barrel. Export them from it, for example: export const users = pgTable(...). " + consequence
+    };
+  }
+  const names = opts.analyzed.map((table) => table.name);
+  const shown = names.slice(0, 6).join(", ");
+  const rest = names.length > 6 ? `, and ${names.length - 6} more` : "";
+  return {
+    code: SCHEMA_FILTERED_CODE,
+    message: `Every table was removed by this config's filters (${SCHEMA_FILTERED_CODE}). ${target} declares ${names.length} table${names.length === 1 ? "" : "s"}: ${shown}${rest}.`,
+    hint: 'Check "include" and "exclude" in your drzl config. A pattern is matched against the whole database table name, with * as the only metacharacter. ' + consequence
+  };
+}
+
 // src/column-filter.ts
 import { parseCheck as parseCheck2 } from "@drzl/validation-core";
 
 // src/doctor.ts
-import { parseCheck } from "@drzl/validation-core";
-import chalk from "chalk";
+import { lengthMeasure, parseCheck } from "@drzl/validation-core";
+import { Chalk as Chalk2 } from "chalk";
+var PLAIN = new Chalk2({ level: 0 });
 var HANDLED_CODES = /* @__PURE__ */ new Set(["DRZL_ANL_UNKNOWN_COLUMN"]);
-function splitPath(path5) {
-  if (!path5) return {};
-  const dot = path5.lastIndexOf(".");
-  if (dot <= 0) return { table: path5 };
-  return { table: path5.slice(0, dot), column: path5.slice(dot + 1) };
+function splitPath(path8) {
+  if (!path8) return {};
+  const dot = path8.lastIndexOf(".");
+  if (dot <= 0) return { table: path8 };
+  return { table: path8.slice(0, dot), column: path8.slice(dot + 1) };
 }
 function namedColumns(parsed) {
   const out = [];
@@ -109,6 +739,7 @@ function namedColumns(parsed) {
   for (const s of parsed.sets ?? []) out.push({ column: s.column, scalar: true });
   for (const l of parsed.lengths ?? []) out.push({ column: l.column, scalar: false });
   for (const c of parsed.cardinalities ?? []) out.push({ column: c.column, scalar: false });
+  for (const n of parsed.nulls ?? []) out.push({ column: n.column, scalar: false });
   for (const r of parsed.rows ?? []) {
     out.push({ column: r.left, scalar: false });
     out.push({ column: r.right, scalar: false });
@@ -137,6 +768,19 @@ function describeShape(c) {
       return "a structured";
   }
 }
+var countNoun = (l) => l.unit === "bytes" ? "byte count" : "character count";
+function countHint(c) {
+  if (c.shape?.kind === "byteString")
+    return "A binary(n)/varbinary(n) column hands the caller a string produced by a lossy decode, so its width is code points coming out and bytes going in and neither is a count of the value in hand. The column already caps itself at n bytes; a second bound stated here would be a different measurement. Leave this one to the database.";
+  return "Only constraints whose meaning is unambiguous are translated, because a validator enforcing a guess rejects rows the database accepts. Your database still enforces this one; nothing DRZL emits does.";
+}
+function declineHint(reason) {
+  if (/combined with/.test(reason))
+    return "Postgres computes numeric arithmetic exactly and JavaScript computes it in binary floating point, so `x + y <= 0.3` accepts (0.1, 0.2) in the database and rejects it in JavaScript. The right translation depends on whether the columns are numeric, double precision or bigint, and the expression does not say. Put the result in a generated column and constrain that, or leave this one to the database.";
+  if (/\bOR\b/.test(reason))
+    return "A disjunction is read only where the whole of it pins one column to a set of values, such as `status = 'a' OR status = 'b'`, which becomes the same enum an IN list does. Anything else is refused whole rather than in part: a row satisfying the other branch is one the database accepts, and enforcing one branch would turn it away.";
+  return "Only constraints whose meaning is unambiguous are translated, because a validator enforcing a guess rejects rows the database accepts. Your database still enforces this one; nothing DRZL emits does.";
+}
 function checkFindings(table) {
   const out = [];
   const byName = new Map(table.columns.map((c) => [c.name, c]));
@@ -152,10 +796,34 @@ function checkFindings(table) {
         table: table.tsName,
         constraint: k.name,
         message: `CHECK ${label} on "${table.tsName}" is not translated: ${parsed.reason}. Expression: ${expr}`,
-        hint: "Only constraints whose meaning is unambiguous are translated, because a validator enforcing a guess rejects rows the database accepts. Your database still enforces this one; nothing DRZL emits does."
+        hint: declineHint(parsed.reason)
       });
       continue;
     }
+    for (const n of parsed.nulls ?? []) {
+      if (n.notNull) continue;
+      out.push({
+        kind: "check-declined",
+        level: "warn",
+        table: table.tsName,
+        constraint: k.name,
+        message: `CHECK ${label} on "${table.tsName}" holds "${n.column} IS NULL", which narrows the column to NULL alone and no generated schema states. Expression: ${expr}`,
+        hint: "A column that may only ever be NULL is usually a constraint written the wrong way round. Drop the column, or state the rule as a CHECK on the column that decides it."
+      });
+    }
+    for (const l of parsed.lengths ?? []) {
+      const col = byName.get(l.column);
+      if (!col || lengthMeasure(col, l)) continue;
+      out.push({
+        kind: "check-uncountable",
+        level: "warn",
+        table: table.tsName,
+        column: l.column,
+        constraint: k.name,
+        message: `CHECK ${label} on "${table.tsName}" counts ${describeShape(col)} column "${l.column}", whose ${countNoun(l)} in JavaScript is not the one the database took, so it is not translated. Expression: ${expr}`,
+        hint: countHint(col)
+      });
+    }
     const seen = /* @__PURE__ */ new Set();
     for (const { column, scalar } of namedColumns(parsed)) {
       if (seen.has(column)) continue;
@@ -267,7 +935,7 @@ var SECTIONS = [
     why: "These get a validator that accepts any value."
   },
   {
-    kinds: ["check-declined", "check-unknown-column", "check-not-scalar"],
+    kinds: ["check-declined", "check-unknown-column", "check-not-scalar", "check-uncountable"],
     title: "CHECK constraints DRZL does not enforce",
     why: "Your database still enforces these. Nothing DRZL generates does."
   },
@@ -296,7 +964,8 @@ function wrap(text, indent, first = indent, width = 96) {
   if (line) lines.push(line);
   return lines.map((l, i) => (i === 0 ? first : indent) + l).join("\n");
 }
-function renderDoctorReport(report) {
+function renderDoctorReport(report, style = PLAIN) {
+  const chalk = style;
   const out = [];
   const plural = (n, one) => `${n} ${one}${n === 1 ? "" : "s"}`;
   out.push(chalk.bold(`DRZL doctor  ${report.schema}`));
@@ -444,87 +1113,1427 @@ function filterColumns(tables, spec) {
   return { tables: out, warnings };
 }
 
-// src/drift.ts
-import { promises as fs } from "fs";
-import path from "path";
-async function snapshotDir(dir) {
-  const out = /* @__PURE__ */ new Map();
-  async function walk(current) {
-    let entries;
-    try {
-      entries = await fs.readdir(current, { withFileTypes: true });
-    } catch {
-      return;
-    }
-    for (const e of entries) {
-      const full = path.join(current, e.name);
-      if (e.isDirectory()) await walk(full);
-      else out.set(path.relative(dir, full), await fs.readFile(full, "utf8"));
-    }
-  }
-  await walk(dir);
-  return out;
+// src/explain.ts
+import { qualifiedForeignTable, qualifiedTableName } from "@drzl/analyzer";
+import { tableConstraints } from "@drzl/validation-core";
+import { Chalk as Chalk3 } from "chalk";
+var PLAIN2 = new Chalk3({ level: 0 });
+function namesOf(table) {
+  const [bare, qualified] = tableAliases(table);
+  return { qualified, name: bare, tsName: table.tsName };
 }
-async function snapshotAll(dirs) {
-  const all = /* @__PURE__ */ new Map();
-  for (const dir of dirs) {
-    for (const [rel, content] of await snapshotDir(dir)) {
-      all.set(path.join(dir, rel), content);
-    }
+var MATCH_ORDER = ["qualified", "name", "tsName"];
+var MATCH_LABELS = {
+  qualified: "the schema-qualified name",
+  name: "the database name",
+  tsName: "the export name"
+};
+function hitsFor(tables, query, fold) {
+  const wanted = fold(query);
+  const hits = [];
+  for (const table of tables) {
+    const names = namesOf(table);
+    const matchedOn = MATCH_ORDER.find((key) => fold(names[key]) === wanted);
+    if (matchedOn) hits.push({ table, matchedOn });
   }
-  return all;
+  return hits;
 }
-function diffSnapshots(before, after) {
-  const out = [];
-  for (const [file, content] of after) {
-    if (!before.has(file)) out.push({ file, status: "added" });
-    else if (before.get(file) !== content) out.push({ file, status: "changed" });
-  }
-  for (const file of before.keys()) {
-    if (!after.has(file)) out.push({ file, status: "removed" });
+var same = (s) => s;
+var folded = (s) => s.toLowerCase();
+function matchTable(tables, query) {
+  for (const [exact, fold] of [
+    [true, same],
+    [false, folded]
+  ]) {
+    const hits = hitsFor(tables, query, fold);
+    if (hits.length === 1) return { kind: "found", exact, ...hits[0] };
+    if (hits.length > 1) return { kind: "ambiguous", exact, hits };
   }
-  return out.sort((a, b) => a.file.localeCompare(b.file));
+  const known = tables.flatMap((t) => {
+    const names = namesOf(t);
+    return t.tsName === names.name ? [names.name] : [names.name, names.tsName];
+  });
+  return { kind: "none", suggestion: nearestKey(query, known) };
 }
-async function restoreSnapshot(before, after) {
-  for (const [file, content] of before) {
-    await fs.mkdir(path.dirname(file), { recursive: true });
-    await fs.writeFile(file, content, "utf8");
-  }
-  for (const file of after.keys()) {
-    if (!before.has(file)) await fs.rm(file, { force: true });
-  }
+function renderLiteral(value) {
+  if (typeof value === "string") return `'${value.replace(/'/g, "\\'")}'`;
+  if (value === null) return "null";
+  if (typeof value === "bigint") return `${value}n`;
+  if (value instanceof Date) return value.toISOString();
+  if (typeof value === "object") return JSON.stringify(value);
+  return String(value);
 }
-
-// src/generator-loader.ts
-var GeneratorNotInstalledError = class extends Error {
-  constructor(specifier, reason) {
-    super(`${specifier} is not installed`);
-    this.specifier = specifier;
-    this.reason = reason;
-    this.name = "GeneratorNotInstalledError";
+function defaultOf(column) {
+  if (column.defaultValue !== void 0) return { kind: "literal", value: column.defaultValue };
+  if (column.defaultExpression) return { kind: "expression", text: column.defaultExpression };
+  return column.hasDefault ? { kind: "runtime" } : null;
+}
+function describeDefault(value) {
+  if (!value) return "";
+  if (value.kind === "literal") return `default ${renderLiteral(value.value)}`;
+  if (value.kind === "expression") return `default ${value.text}`;
+  return "has default";
+}
+function describeShape2(shape) {
+  switch (shape.kind) {
+    case "buffer":
+      return "binary payload, carried as a Uint8Array";
+    case "json":
+      return "any JSON value, checked recursively";
+    case "tuple":
+      return `tuple of ${shape.length} numbers`;
+    case "numberObject":
+      return `object of numbers: ${shape.fields.join(", ")}`;
+    case "numberVector":
+      return shape.length ? `numeric vector of ${shape.length}` : "numeric vector";
+    case "custom":
+      return shape.sqlType ? `customType, declared ${shape.sqlType}, with no runtime shape to read` : "customType, with no runtime shape to read";
+    case "bitstring":
+      if (shape.length === void 0) return "string of 0 and 1";
+      return shape.exact ? `string of ${shape.length} digits, each 0 or 1` : `string of at most ${shape.length} digits, each 0 or 1`;
+    case "byteString":
+      return shape.length ? `bytes, declared width ${shape.length}` : "bytes";
+  }
+}
+function capReason(column, narrowedBySet) {
+  if (column.shape)
+    return `"${column.name}" is a structured column, whose value space is not stated as a width`;
+  if (narrowedBySet)
+    return `a CHECK narrows "${column.name}" to a set of literals, which states its value space instead`;
+  if (column.enumValues?.length)
+    return `"${column.name}" is an enum, and its members state its value space instead`;
+  if (column.tsType !== "string")
+    return `"${column.name}" does not arrive as a string, so there is nothing to measure`;
+  if (column.format)
+    return `the ${column.format} format replaces the width on "${column.name}" rather than adding to it`;
+  return `the generated schemas state "${column.name}" some other way`;
+}
+function factsFor(column, opts) {
+  const facts = [];
+  const state = (text) => facts.push({ text, stated: true });
+  if (column.arrayDimensions) {
+    state(
+      column.arrayDimensions === 1 ? "an array of the type above" : `an array of ${column.arrayDimensions} dimensions`
+    );
+  }
+  if (column.shape) state(describeShape2(column.shape));
+  if (column.enumValues?.length) {
+    state(`one of ${column.enumValues.map((v) => `'${v}'`).join(", ")}`);
+  }
+  if (column.format) state(`text in the ${column.format} format the database parses`);
+  if (column.min !== void 0 && column.max !== void 0) {
+    state(`${column.min} to ${column.max}`);
+  } else if (column.min !== void 0) state(`at least ${column.min}`);
+  else if (column.max !== void 0) state(`at most ${column.max}`);
+  if (column.integer === true) state("whole numbers only");
+  if (column.integer === false) state("fractions allowed");
+  if (column.allowsNaN !== void 0) {
+    state(column.allowsNaN ? "NaN is stored and returned" : "NaN is refused");
+  }
+  if (column.allowsInfinity !== void 0) {
+    state(column.allowsInfinity ? "Infinity is stored and returned" : "Infinity is refused");
+  }
+  for (const [value2, text] of [
+    [column.maxLength, `at most ${column.maxLength} characters`],
+    [column.maxBytes, `at most ${column.maxBytes} bytes`]
+  ]) {
+    if (value2 === void 0) continue;
+    facts.push(
+      opts.capStated ? { text, stated: true } : { text, stated: false, reason: capReason(column, opts.narrowedBySet) }
+    );
+  }
+  const value = defaultOf(column);
+  if (value?.kind === "literal") state(`defaults to ${renderLiteral(value.value)}`);
+  else if (value?.kind === "expression") state(`defaults to ${value.text}, evaluated by the database`);
+  else if (value?.kind === "runtime") {
+    facts.push({
+      text: "has a default",
+      stated: false,
+      reason: "the value is produced at insert time, by the database or by a Drizzle function, so the field is optional on insert and no schema states what it becomes"
+    });
+  }
+  if (column.isGenerated) {
+    state("generated by the database, so it is left out of insert and update schemas");
+  }
+  return facts;
+}
+function issueTouches(issue, table) {
+  if (!issue.path) return false;
+  const names = namesOf(table);
+  const own = [names.qualified, names.name, names.tsName, table.name];
+  if (own.includes(issue.path)) return true;
+  const dot = issue.path.lastIndexOf(".");
+  return dot > 0 && own.includes(issue.path.slice(0, dot));
+}
+function issueColumn(issue, table) {
+  const path8 = issue.path ?? "";
+  const names = namesOf(table);
+  for (const prefix of [names.qualified, names.tsName, names.name, table.name]) {
+    if (path8.startsWith(`${prefix}.`)) {
+      const rest = path8.slice(prefix.length + 1);
+      if (table.columns.some((c) => c.name === rest)) return rest;
+    }
+  }
+  return void 0;
+}
+var RELATION_CODES = /* @__PURE__ */ new Set(["DRZL_ANL_RELATIONS", "DRZL_ANL_REL_V2"]);
+function gapsFor(table, constraints, issues) {
+  const gaps = [];
+  for (const constraint of constraints) {
+    for (const part of constraint.unenforced ?? []) {
+      gaps.push({
+        kind: "check",
+        subject: constraint.name ?? constraint.id,
+        // `part.part` already carries the constraint name where the declaration had one, because
+        // that is the text an emitted schema would have attached. The renderer prefixes `subject`
+        // only when it is not already there, so a named CHECK is not announced twice.
+        message: `${part.part} is not enforced: ${part.reason}.`,
+        hint: "Your database still enforces it. Nothing DRZL generates does."
+      });
+    }
+  }
+  for (const issue of issues) {
+    if (issue.level === "info") continue;
+    if (!issueTouches(issue, table)) continue;
+    const subject = issueColumn(issue, table);
+    gaps.push({
+      kind: RELATION_CODES.has(issue.code) ? "relation" : subject ? "column" : "analyzer",
+      ...subject ? { subject } : {},
+      message: issue.message,
+      ...issue.hint ? { hint: issue.hint } : {}
+    });
+  }
+  return gaps;
+}
+function explainTable(analysis, match, options = {}) {
+  const table = match.table;
+  const qualified = qualifiedTableName(table);
+  const constraints = tableConstraints(table).constraints;
+  const capped = new Set(
+    constraints.filter((c) => c.kind === "maxLength" || c.kind === "maxBytes").flatMap((c) => c.columns)
+  );
+  const narrowedBySet = new Set(
+    constraints.filter((c) => c.values).map((c) => c.values.column)
+  );
+  const primaryKeyColumns = new Set(table.primaryKey?.columns ?? []);
+  const singleColumnUnique = new Set(
+    (table.unique ?? []).filter((u) => u.columns.length === 1).map((u) => u.columns[0])
+  );
+  const columns = table.columns.map((column) => ({
+    name: column.name,
+    tsType: column.tsType,
+    dbType: column.dbType,
+    ...column.sqlType ? { sqlType: column.sqlType } : {},
+    nullable: column.nullable,
+    hasDefault: column.hasDefault,
+    default: defaultOf(column),
+    isGenerated: column.isGenerated,
+    inPrimaryKey: primaryKeyColumns.has(column.name),
+    unique: singleColumnUnique.has(column.name),
+    ...column.references ? { references: column.references } : {},
+    ...column.enumValues ? { enumValues: column.enumValues } : {},
+    ...column.arrayDimensions ? { arrayDimensions: column.arrayDimensions } : {},
+    ...column.shape ? { shape: column.shape } : {},
+    facts: factsFor(column, {
+      capStated: capped.has(column.name),
+      narrowedBySet: narrowedBySet.has(column.name)
+    })
+  }));
+  const relations = analysis.relations.filter((r) => r.from === qualified || r.to === qualified || r.via === qualified).map((r) => ({ ...r, outgoing: r.from === qualified }));
+  const keyColumns = table.columns.filter((c) => primaryKeyColumns.has(c.name));
+  const primaryKey = table.primaryKey?.columns.length ? {
+    ...table.primaryKey.name ? { name: table.primaryKey.name } : {},
+    columns: [...table.primaryKey.columns],
+    generated: keyColumns.length > 0 && keyColumns.every((c) => c.isGenerated || c.hasDefault)
+  } : null;
+  const removed = options.keptColumns ? table.columns.map((c) => c.name).filter((name) => !options.keptColumns.includes(name)) : [];
+  return {
+    name: table.name,
+    tsName: table.tsName,
+    ...table.schema ? { schema: table.schema } : {},
+    qualified,
+    addressable: addressableName(table),
+    readOnly: !!table.readOnly,
+    matchedOn: match.matchedOn,
+    matchedExactly: match.exact,
+    ...options.keptTables && !options.keptTables.includes(qualified) ? { excludedByConfig: true } : {},
+    ...removed.length ? { columnsRemovedByConfig: removed } : {},
+    columns,
+    primaryKey,
+    unique: (table.unique ?? []).map((u) => ({
+      ...u.name ? { name: u.name } : {},
+      columns: [...u.columns]
+    })),
+    indexes: (table.indexes ?? []).map((i) => ({
+      ...i.name ? { name: i.name } : {},
+      columns: [...i.columns]
+    })),
+    foreignKeys: (table.foreignKeys ?? []).map((fk) => ({
+      ...fk.name ? { name: fk.name } : {},
+      columns: [...fk.columns],
+      references: { table: qualifiedForeignTable(fk), columns: [...fk.foreignColumns] },
+      ...fk.onDelete ? { onDelete: fk.onDelete } : {},
+      ...fk.onUpdate ? { onUpdate: fk.onUpdate } : {}
+    })),
+    relations,
+    constraints,
+    gaps: gapsFor(table, constraints, analysis.issues)
+  };
+}
+function summarize(analysis) {
+  return analysis.tables.map((table) => ({
+    name: table.name,
+    tsName: table.tsName,
+    ...table.schema ? { schema: table.schema } : {},
+    qualified: qualifiedTableName(table),
+    columns: table.columns.length,
+    checks: table.checks?.length ?? 0,
+    gaps: gapsFor(table, tableConstraints(table).constraints, analysis.issues).length
+  }));
+}
+var WIDTH = 80;
+var pad = (text, width) => text + " ".repeat(Math.max(0, width - text.length));
+var widest = (values) => values.reduce((n, v) => Math.max(n, v.length), 0);
+function wrap2(text, indent, first = indent) {
+  const lines = [];
+  let line = "";
+  for (const word of String(text).split(/\s+/)) {
+    if (line && `${line} ${word}`.length + indent.length > WIDTH) {
+      lines.push(line);
+      line = word;
+    } else {
+      line = line ? `${line} ${word}` : word;
+    }
+  }
+  if (line) lines.push(line);
+  return lines.map((l, i) => (i === 0 ? first : indent) + l).join("\n");
+}
+function renderTsType(column) {
+  return column.tsType + "[]".repeat(column.arrayDimensions ?? 0);
+}
+function columnNotes(column) {
+  const notes = [];
+  if (column.inPrimaryKey) notes.push("pk");
+  if (column.unique) notes.push("unique");
+  if (column.references) {
+    notes.push(`fk -> ${column.references.table}.${column.references.column}`);
+  }
+  if (column.isGenerated) notes.push("generated");
+  const value = describeDefault(column.default);
+  if (value && !column.isGenerated) notes.push(value);
+  return notes.join(", ");
+}
+function constraintLines(constraint, style, labelWidth) {
+  const label = constraint.name ?? "";
+  const verdict = constraint.enforced ? style.green("enforced") : style.yellow("not enforced by any generated schema");
+  const out = [`  ${pad(label, labelWidth)}  ${constraint.rule}`];
+  out.push(`  ${" ".repeat(labelWidth)}  ${verdict}`);
+  for (const part of constraint.unenforced ?? []) {
+    out.push(style.dim(wrap2(part.reason, " ".repeat(labelWidth + 4))));
+  }
+  return out;
+}
+function renderExplanation(explanation, context, style = PLAIN2) {
+  const out = [];
+  const plural = (n, one) => `${n} ${one}${n === 1 ? "" : "s"}`;
+  out.push(style.bold(explanation.qualified) + style.dim(`  ${context.schema}`));
+  const identity = [
+    context.dialect,
+    `table "${explanation.name}"`,
+    `export "${explanation.tsName}"`,
+    plural(explanation.columns.length, "column")
+  ];
+  if (explanation.readOnly) identity.push("read-only, so no insert or update schema is emitted");
+  out.push(style.dim("  " + identity.join(", ")));
+  if (!explanation.matchedExactly) {
+    out.push(style.dim(`  matched on ${MATCH_LABELS[explanation.matchedOn]}, ignoring case`));
+  }
+  if (explanation.excludedByConfig) {
+    out.push("");
+    out.push(style.yellow("  This config's include/exclude removes this table."));
+    out.push(style.dim("  No generator sees it, so nothing below reaches any emitted file."));
+  }
+  if (explanation.columnsRemovedByConfig?.length) {
+    out.push("");
+    out.push(
+      style.yellow(
+        `  This config's columns filter removes ${explanation.columnsRemovedByConfig.length} of these columns: ${explanation.columnsRemovedByConfig.join(", ")}.`
+      )
+    );
+  }
+  out.push("");
+  out.push(style.bold("Columns"));
+  const tsTypes = explanation.columns.map(renderTsType);
+  const nameWidth = widest(["COLUMN", ...explanation.columns.map((c) => c.name)]);
+  const tsWidth = widest(["TS TYPE", ...tsTypes]);
+  const sqlWidth = widest(["SQL TYPE", ...explanation.columns.map((c) => c.sqlType ?? c.dbType)]);
+  out.push(
+    style.dim(
+      `  ${pad("COLUMN", nameWidth)}  ${pad("TS TYPE", tsWidth)}  ${pad("SQL TYPE", sqlWidth)}  NULL`
+    )
+  );
+  explanation.columns.forEach((column, i) => {
+    const sql = column.sqlType ?? column.dbType;
+    const notes = columnNotes(column);
+    const nullable = column.nullable ? "yes" : "no";
+    out.push(
+      `  ${pad(column.name, nameWidth)}  ${pad(tsTypes[i], tsWidth)}  ${pad(sql, sqlWidth)}  ` + // Padded only when something follows it: a trailing run of spaces on every second row is
+      // invisible in a terminal and is the first thing a test diff shows.
+      (notes ? `${pad(nullable, 4)}  ${style.dim(notes)}` : nullable)
+    );
+  });
+  const withFacts = explanation.columns.filter((c) => c.facts.length);
+  if (withFacts.length) {
+    out.push("");
+    out.push(style.bold("What the generators read off each column"));
+    const factWidth = widest(withFacts.map((c) => c.name));
+    for (const column of withFacts) {
+      let first = true;
+      for (const fact of column.facts) {
+        const label = first ? pad(column.name, factWidth) : " ".repeat(factWidth);
+        first = false;
+        out.push(`  ${label}  ${fact.stated ? fact.text : style.yellow(fact.text)}`);
+        if (fact.stated) continue;
+        out.push(
+          style.dim(
+            wrap2(
+              `not stated by any generated schema: ${fact.reason}`,
+              " ".repeat(factWidth + 4)
+            )
+          )
+        );
+      }
+    }
+  }
+  out.push("");
+  out.push(style.bold("Keys"));
+  if (explanation.primaryKey) {
+    const pk = explanation.primaryKey;
+    out.push(
+      `  PRIMARY KEY (${pk.columns.join(", ")})` + (pk.generated ? style.dim("  filled in by the database") : "")
+    );
+    if (pk.columns.length > 1) {
+      out.push(
+        style.dim(
+          wrap2(
+            `The service and router generators key getById, update and delete on "${pk.columns[0]}" alone, so those operations match on part of this key.`,
+            "    "
+          )
+        )
+      );
+    }
+  } else {
+    out.push(style.yellow("  No primary key."));
+    out.push(
+      style.dim(
+        wrap2(
+          'The service and router generators fall back to a column named "id".',
+          "    "
+        )
+      )
+    );
+  }
+  for (const unique of explanation.unique) {
+    out.push(`  UNIQUE (${unique.columns.join(", ")})` + (unique.name ? style.dim(`  ${unique.name}`) : ""));
+  }
+  for (const index of explanation.indexes) {
+    out.push(style.dim(`  INDEX (${index.columns.join(", ")})${index.name ? `  ${index.name}` : ""}`));
+  }
+  if (explanation.foreignKeys.length) {
+    out.push("");
+    out.push(style.bold("Foreign keys"));
+    for (const fk of explanation.foreignKeys) {
+      const actions = [
+        fk.onDelete ? `ON DELETE ${fk.onDelete}` : "",
+        fk.onUpdate ? `ON UPDATE ${fk.onUpdate}` : ""
+      ].filter(Boolean).join(" ");
+      out.push(
+        `  (${fk.columns.join(", ")}) -> ${fk.references.table} (${fk.references.columns.join(", ")})` + (actions ? style.dim(`  ${actions}`) : "")
+      );
+    }
+  }
+  if (explanation.relations.length) {
+    out.push("");
+    out.push(style.bold("Relations"));
+    for (const relation of explanation.relations) {
+      const via = relation.via ? ` through ${relation.via}` : "";
+      out.push(
+        `  ${relation.from} -> ${relation.to}${via}` + style.dim(`  ${relation.kind}`)
+      );
+    }
+  }
+  const checks = explanation.constraints.filter((c) => c.kind === "check");
+  if (checks.length) {
+    out.push("");
+    out.push(style.bold("CHECK constraints, as DRZL parsed them"));
+    const labelWidth = widest(checks.map((c) => c.name ?? ""));
+    for (const check of checks) out.push(...constraintLines(check, style, labelWidth));
+  }
+  out.push("");
+  if (!explanation.gaps.length) {
+    out.push(style.green("Nothing about this table was dropped or left unrecognised."));
+    return out.join("\n");
+  }
+  out.push(style.yellow(`Not understood  (${explanation.gaps.length})`));
+  out.push(style.dim("  These are in your schema and are not in anything DRZL generates."));
+  out.push("");
+  const groups = /* @__PURE__ */ new Map();
+  for (const gap of explanation.gaps) {
+    const key = gap.hint ?? "";
+    groups.set(key, [...groups.get(key) ?? [], gap]);
+  }
+  for (const [hint, items] of groups) {
+    for (const gap of items) {
+      const named = gap.subject && !gap.message.startsWith(gap.subject);
+      out.push(wrap2((named ? `${gap.subject}: ` : "") + gap.message, "    ", `  ${style.dim("-")} `));
+    }
+    if (hint) out.push(style.dim(wrap2(hint, "    ")));
+    out.push("");
+  }
+  return out.join("\n").replace(/\n+$/, "");
+}
+function renderIndex(tables, context, style = PLAIN2) {
+  const out = [];
+  const plural = (n, one) => `${n} ${one}${n === 1 ? "" : "s"}`;
+  out.push(style.bold(context.schema) + style.dim(`  ${context.dialect}`));
+  out.push(style.dim(`  ${plural(tables.length, "table")}`));
+  out.push("");
+  const nameWidth = widest(["TABLE", ...tables.map((t) => t.qualified)]);
+  const tsWidth = widest(["EXPORT", ...tables.map((t) => t.tsName)]);
+  out.push(style.dim(`  ${pad("TABLE", nameWidth)}  ${pad("EXPORT", tsWidth)}  COLUMNS`));
+  for (const table of tables) {
+    const columns = String(table.columns);
+    out.push(
+      `  ${pad(table.qualified, nameWidth)}  ${pad(table.tsName, tsWidth)}  ` + (table.gaps ? `${pad(columns, 7)}  ` + style.yellow(`${plural(table.gaps, "thing")} not understood`) : columns)
+    );
+  }
+  out.push("");
+  out.push(style.dim("  drzl explain <table>  for one of them in full"));
+  return out.join("\n");
+}
+var NO_SUCH_TABLE_CODE = "DRZL_EXPLAIN_001";
+var AMBIGUOUS_TABLE_CODE = "DRZL_EXPLAIN_002";
+var NAME_CAP = 12;
+function noSuchTableProblem(query, tables, suggestion) {
+  const names = tables.map((t) => displayTableName(t));
+  const shown = names.slice(0, NAME_CAP).join(", ");
+  const rest = names.length > NAME_CAP ? `, and ${names.length - NAME_CAP} more` : "";
+  return {
+    code: NO_SUCH_TABLE_CODE,
+    message: `No table called "${query}" (${NO_SUCH_TABLE_CODE}). ` + (names.length ? `This schema declares ${names.length} table${names.length === 1 ? "" : "s"}: ${shown}${rest}.` : "This schema declares no tables."),
+    hint: suggestion ? `Did you mean "${suggestion}"?` : "A table is matched by its database name, by its schema-qualified name, or by the name it is exported under, ignoring case where nothing matches exactly."
+  };
+}
+function ambiguousTableProblem(query, hits) {
+  const named = hits.map((hit) => `${addressableName(hit.table)} (exported as ${hit.table.tsName})`).join(", ");
+  return {
+    code: AMBIGUOUS_TABLE_CODE,
+    message: `"${query}" names ${hits.length} tables (${AMBIGUOUS_TABLE_CODE}): ${named}.`,
+    hint: `Name one of them exactly, for example "${addressableName(hits[0].table)}".`
+  };
+}
+
+// src/drizzle-kit.ts
+import * as fs from "fs";
+import * as path from "path";
+var DRIZZLE_KIT_CONFIG_CANDIDATES = [
+  "drizzle.config.ts",
+  "drizzle.config.js",
+  "drizzle.config.json"
+];
+var CODE_EXTENSIONS = /* @__PURE__ */ new Set([".ts", ".js", ".cjs", ".mjs", ".mts", ".cts"]);
+function findDrizzleKitConfig(cwd) {
+  for (const name of DRIZZLE_KIT_CONFIG_CANDIDATES) {
+    const p = path.join(cwd, name);
+    if (fs.existsSync(p)) return p;
+  }
+  return null;
+}
+async function loadDrizzleKitConfig(p) {
+  let raw;
+  try {
+    raw = await importFreshConfigModule(p);
+  } catch (e) {
+    throw new Error(
+      `drzl config: failed to load the drizzle-kit config at ${p}: ${e?.message ?? e}`
+    );
+  }
+  if (!raw || typeof raw !== "object") {
+    throw new Error(`drzl config: ${p} did not export a drizzle-kit config object.`);
+  }
+  const record = raw;
+  const schema = record.schema;
+  if (schema !== void 0 && typeof schema !== "string" && !(Array.isArray(schema) && schema.every((s) => typeof s === "string"))) {
+    throw new Error(
+      `drzl config: "schema" in ${p} must be a string or an array of strings, matching drizzle-kit's own Config type.`
+    );
+  }
+  return {
+    path: p,
+    schema,
+    dialect: typeof record.dialect === "string" ? record.dialect : void 0,
+    casing: typeof record.casing === "string" ? record.casing : void 0
+  };
+}
+function hasGlobMagic(entry) {
+  return /[*?{}[\]]/.test(entry) || /[!@+]\(/.test(entry);
+}
+function staticGlobBase(entry, cwd) {
+  const segments = entry.split("/");
+  const kept = [];
+  for (const s of segments) {
+    if (hasGlobMagic(s)) break;
+    kept.push(s);
+  }
+  const joined = kept.join("/");
+  const base = path.resolve(cwd, joined || ".");
+  if (fs.existsSync(base) && fs.statSync(base).isDirectory()) return base;
+  return path.dirname(base);
+}
+function filesOneLevel(dir) {
+  const out = [];
+  for (const name of fs.readdirSync(dir)) {
+    const full = path.join(dir, name);
+    if (!fs.lstatSync(full).isDirectory()) out.push(full);
+  }
+  return out;
+}
+function expandSchemaPaths(entries, cwd) {
+  const list = typeof entries === "string" ? [entries] : entries;
+  const files = /* @__PURE__ */ new Set();
+  const watchDirs = /* @__PURE__ */ new Set();
+  for (const entry of list) {
+    if (hasGlobMagic(entry)) {
+      watchDirs.add(staticGlobBase(entry, cwd));
+      for (const match of fs.globSync(entry, { cwd })) {
+        const full2 = path.resolve(cwd, match);
+        if (fs.existsSync(full2) && fs.statSync(full2).isDirectory()) {
+          for (const f of filesOneLevel(full2)) files.add(f);
+        } else {
+          files.add(full2);
+        }
+      }
+      continue;
+    }
+    const full = path.resolve(cwd, entry);
+    let stat = null;
+    try {
+      stat = fs.statSync(full);
+    } catch {
+      watchDirs.add(path.dirname(full));
+      continue;
+    }
+    if (stat.isDirectory()) {
+      watchDirs.add(full);
+      for (const f of filesOneLevel(full)) files.add(f);
+    } else {
+      watchDirs.add(path.dirname(full));
+      files.add(full);
+    }
+  }
+  const kept = [...files].filter((f) => CODE_EXTENSIONS.has(path.extname(f).toLowerCase()));
+  return { files: kept.sort(), watchDirs: [...watchDirs] };
+}
+function mapDrizzleKitDialect(declared) {
+  if (!declared) return null;
+  const map = {
+    postgresql: "postgres",
+    mysql: "mysql",
+    sqlite: "sqlite",
+    turso: "sqlite",
+    singlestore: "singlestore",
+    gel: "gel"
+  };
+  if (declared in map) return map[declared];
+  const analyzerDialects = [
+    "sqlite",
+    "postgres",
+    "mysql",
+    "singlestore",
+    "mssql",
+    "cockroach",
+    "gel"
+  ];
+  return analyzerDialects.includes(declared) ? declared : null;
+}
+function dialectMismatchWarning(args) {
+  const expected = mapDrizzleKitDialect(args.declared);
+  if (!expected) return null;
+  if (args.analyzed === "unknown") return null;
+  if (args.analyzed === expected) return null;
+  return `drzl: ${args.configPath} declares dialect "${args.declared}", but the schema analyzed as "${args.analyzed}". DRZL follows the schema; if the schema files are the right ones, the dialect in that config is stale.`;
+}
+async function resolveSchemaSource(cfg, cwd = process.cwd()) {
+  if (cfg.schema) {
+    const warnings = [];
+    if (cfg.drizzleKit === true || typeof cfg.drizzleKit === "string") {
+      warnings.push(
+        `drzl config: both "schema" and "drizzleKit" are set. "schema" wins, so the drizzle-kit config was not read; remove one of the two to silence this.`
+      );
+    }
+    return {
+      source: "drzl",
+      schema: cfg.schema,
+      watchDirs: [path.dirname(path.resolve(cwd, cfg.schema))],
+      warnings
+    };
+  }
+  if (cfg.drizzleKit === false) {
+    throw new Error(
+      `drzl config: no "schema" is set and "drizzleKit" is false, so the drizzle-kit fallback is disabled. Set "schema".`
+    );
+  }
+  let configPath;
+  if (typeof cfg.drizzleKit === "string") {
+    configPath = path.resolve(cwd, cfg.drizzleKit);
+    if (!fs.existsSync(configPath)) {
+      throw new Error(`drzl config: "drizzleKit" points at ${configPath}, which does not exist.`);
+    }
+  } else {
+    const found = findDrizzleKitConfig(cwd);
+    if (!found) {
+      const looked = DRIZZLE_KIT_CONFIG_CANDIDATES.join(", ");
+      throw new Error(
+        cfg.drizzleKit === true ? `drzl config: "drizzleKit" is set, but no drizzle-kit config was found (looked for ${looked} in ${cwd}). Create one, or point "drizzleKit" at its path.` : `drzl config: no "schema" is set and no drizzle-kit config was found (looked for ${looked} in ${cwd}). Set "schema" in your drzl config, or add "drizzleKit" naming your drizzle-kit config file.`
+      );
+    }
+    configPath = found;
+  }
+  const kit = await loadDrizzleKitConfig(configPath);
+  if (kit.schema === void 0) {
+    throw new Error(
+      `drzl config: ${configPath} has no "schema" entry, so there is nothing to analyze. Set "schema" there, or set "schema" in your drzl config.`
+    );
+  }
+  const { files, watchDirs } = expandSchemaPaths(kit.schema, cwd);
+  if (!files.length) {
+    const shown = (typeof kit.schema === "string" ? [kit.schema] : kit.schema).map((s) => JSON.stringify(s)).join(", ");
+    throw new Error(
+      `drzl config: the "schema" patterns in ${configPath} matched no schema files: ${shown}. DRZL expands them the way drizzle-kit does; check them against your tree.`
+    );
+  }
+  return {
+    source: "drizzle-kit",
+    schema: files,
+    watchDirs,
+    drizzleKitConfigPath: configPath,
+    drizzleKitDialect: kit.dialect,
+    warnings: []
+  };
+}
+
+// src/drift.ts
+import { promises as fs2 } from "fs";
+import path2 from "path";
+async function snapshotDir(dir) {
+  const out = /* @__PURE__ */ new Map();
+  async function walk(current) {
+    let entries;
+    try {
+      entries = await fs2.readdir(current, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const e of entries) {
+      const full = path2.join(current, e.name);
+      if (e.isDirectory()) await walk(full);
+      else out.set(path2.relative(dir, full), await fs2.readFile(full, "utf8"));
+    }
+  }
+  await walk(dir);
+  return out;
+}
+async function snapshotAll(dirs) {
+  const all = /* @__PURE__ */ new Map();
+  for (const dir of dirs) {
+    for (const [rel, content] of await snapshotDir(dir)) {
+      all.set(path2.join(dir, rel), content);
+    }
+  }
+  return all;
+}
+function diffSnapshots(before, after) {
+  const out = [];
+  for (const [file, content] of after) {
+    if (!before.has(file)) out.push({ file, status: "added" });
+    else if (before.get(file) !== content) out.push({ file, status: "changed" });
+  }
+  for (const file of before.keys()) {
+    if (!after.has(file)) out.push({ file, status: "removed" });
+  }
+  return out.sort((a, b) => a.file.localeCompare(b.file));
+}
+async function restoreSnapshot(before, after) {
+  for (const [file, content] of before) {
+    await fs2.mkdir(path2.dirname(file), { recursive: true });
+    await fs2.writeFile(file, content, "utf8");
+  }
+  for (const file of after.keys()) {
+    if (!before.has(file)) await fs2.rm(file, { force: true });
+  }
+}
+
+// src/emit-plan.ts
+import { promises as fs3 } from "fs";
+import path3 from "path";
+var EmitPlan = class {
+  constructor(options) {
+    this.byFile = /* @__PURE__ */ new Map();
+    this.dirs = /* @__PURE__ */ new Set();
+    this.writes = options.write;
+    this.existing = options.existing;
+  }
+  async mkdir(dir) {
+    this.dirs.add(dir);
+    if (this.writes) await fs3.mkdir(dir, { recursive: true });
+  }
+  async writeFile(file, contents) {
+    const prior = this.byFile.get(file);
+    const before = prior ? prior.before : await this.read(file);
+    this.byFile.set(file, {
+      file,
+      before,
+      after: contents,
+      verdict: before === null ? "created" : before === contents ? "unchanged" : "changed"
+    });
+    if (this.writes) await fs3.writeFile(file, contents, "utf8");
+  }
+  async read(file) {
+    if (this.existing) return this.existing.get(file) ?? null;
+    try {
+      return await fs3.readFile(file, "utf8");
+    } catch {
+      return null;
+    }
+  }
+  /** Every directory a generator asked for, whether or not it was created. */
+  get directories() {
+    return [...this.dirs];
+  }
+  /** Every recorded file, in the order it was first written. */
+  get files() {
+    return [...this.byFile.values()];
+  }
+  /**
+   * The verdicts for a list of paths, in the order given.
+   *
+   * A path with no verdict is a path the generator reported writing without routing it through
+   * the sink, which is the one shape a version mismatch takes: a `@drzl/cli` that knows about
+   * `fileSink` beside a generator package that predates it. It is returned rather than thrown on
+   * so the caller can name the generator; see `unrecorded`.
+   */
+  verdictsFor(paths) {
+    return paths.map((p) => this.byFile.get(p));
+  }
+  /** The paths a generator claims to have written that never reached this sink. */
+  unrecorded(paths) {
+    return paths.filter((p) => !this.byFile.has(p));
+  }
+  counts(paths) {
+    const entries = paths ? this.verdictsFor(paths).filter(Boolean) : this.files;
+    const counts = { total: entries.length, created: 0, changed: 0, unchanged: 0 };
+    for (const e of entries) counts[e.verdict]++;
+    return counts;
   }
 };
-function isPackageMissing(err, specifier) {
-  const code = err?.code;
-  if (code !== "ERR_MODULE_NOT_FOUND") return false;
-  const message = err?.message;
-  return typeof message === "string" && message.includes(`'${specifier}'`);
+function describeCounts(counts) {
+  const parts = [];
+  if (counts.created) parts.push(`${counts.created} created`);
+  if (counts.changed) parts.push(`${counts.changed} changed`);
+  if (counts.unchanged) parts.push(`${counts.unchanged} unchanged`);
+  return parts.join(", ") || "nothing to write";
+}
+function pendingChanges(plan) {
+  return plan.files.filter((f) => f.verdict !== "unchanged").sort((a, b) => a.file.localeCompare(b.file));
+}
+function driftStatusOf(verdict) {
+  return verdict === "created" ? "added" : "changed";
+}
+async function verifyNothingWasWritten(dirs, before) {
+  const after = await snapshotAll(dirs);
+  const drift = diffSnapshots(before, after);
+  if (!drift.length) return [];
+  await restoreSnapshot(before, after);
+  return drift.map((d) => d.file).sort();
+}
+function displayPath(file, cwd = process.cwd()) {
+  const rel = path3.relative(cwd, file);
+  return rel && !rel.startsWith("..") ? rel : file;
+}
+
+// src/unified-diff.ts
+var DEFAULT_DIFF_LIMITS = {
+  maxLines: 4e3,
+  maxEdits: 1500,
+  context: 3
+};
+function toLines(text) {
+  if (text === "") return { lines: [], newlineAtEnd: true };
+  const newlineAtEnd = text.endsWith("\n");
+  const lines = text.split("\n");
+  if (newlineAtEnd) lines.pop();
+  return { lines, newlineAtEnd };
+}
+function shortestEdit(a, b, maxEdits) {
+  const n = a.length;
+  const m = b.length;
+  const max = n + m;
+  const offset = max;
+  const v = new Int32Array(2 * max + 1);
+  const trace = [];
+  const limit = Math.min(max, maxEdits);
+  for (let d = 0; d <= limit; d++) {
+    trace.push(Int32Array.prototype.slice.call(v));
+    for (let k = -d; k <= d; k += 2) {
+      let x;
+      if (k === -d || k !== d && v[k - 1 + offset] < v[k + 1 + offset]) x = v[k + 1 + offset];
+      else x = v[k - 1 + offset] + 1;
+      let y = x - k;
+      while (x < n && y < m && a[x] === b[y]) {
+        x++;
+        y++;
+      }
+      v[k + offset] = x;
+      if (x >= n && y >= m) return trace;
+    }
+  }
+  return null;
+}
+function backtrack(trace, a, b) {
+  const max = a.length + b.length;
+  const offset = max;
+  let x = a.length;
+  let y = b.length;
+  const ops = [];
+  for (let d = trace.length - 1; d >= 0; d--) {
+    const v = trace[d];
+    const k = x - y;
+    let prevK;
+    if (k === -d || k !== d && v[k - 1 + offset] < v[k + 1 + offset]) prevK = k + 1;
+    else prevK = k - 1;
+    const prevX = v[prevK + offset];
+    const prevY = prevX - prevK;
+    while (x > prevX && y > prevY) {
+      x--;
+      y--;
+      ops.push({ kind: "equal", a: x, b: y });
+    }
+    if (d > 0) {
+      if (x === prevX) {
+        y--;
+        ops.push({ kind: "insert", a: x, b: y });
+      } else {
+        x--;
+        ops.push({ kind: "delete", a: x, b: y });
+      }
+    }
+  }
+  ops.reverse();
+  return ops;
+}
+function diffLines(a, b, maxEdits) {
+  let head = 0;
+  while (head < a.length && head < b.length && a[head] === b[head]) head++;
+  let tail = 0;
+  while (tail < a.length - head && tail < b.length - head && a[a.length - 1 - tail] === b[b.length - 1 - tail]) {
+    tail++;
+  }
+  const midA = a.slice(head, a.length - tail);
+  const midB = b.slice(head, b.length - tail);
+  let mid = [];
+  if (midA.length || midB.length) {
+    const trace = shortestEdit(midA, midB, maxEdits);
+    if (!trace) return null;
+    mid = backtrack(trace, midA, midB);
+  }
+  const ops = [];
+  for (let i = 0; i < head; i++) ops.push({ kind: "equal", a: i, b: i });
+  for (const op of mid) ops.push({ kind: op.kind, a: op.a + head, b: op.b + head });
+  for (let i = 0; i < tail; i++) {
+    ops.push({ kind: "equal", a: a.length - tail + i, b: b.length - tail + i });
+  }
+  return ops;
+}
+function unifiedDiff(before, after, opts) {
+  if (before === after) return "";
+  const limits = { ...DEFAULT_DIFF_LIMITS, ...opts.limits ?? {} };
+  const from = toLines(before);
+  const to = toLines(after);
+  const beforeLines = withNoNewlineMark(from);
+  const afterLines = withNoNewlineMark(to);
+  if (from.lines.length > limits.maxLines || to.lines.length > limits.maxLines) {
+    return `--- ${opts.fromLabel}
++++ ${opts.toLabel}
+@@ no line diff @@
+  ${from.lines.length} lines on disk, ${to.lines.length} lines regenerated. Not diffed: the file is longer than the ${limits.maxLines}-line cap.
+`;
+  }
+  const ops = diffLines(beforeLines, afterLines, limits.maxEdits);
+  if (!ops) {
+    return `--- ${opts.fromLabel}
++++ ${opts.toLabel}
+@@ no line diff @@
+  ${from.lines.length} lines on disk, ${to.lines.length} lines regenerated. Not diffed: the two differ by more than the ${limits.maxEdits}-edit cap, so the whole file is effectively new.
+`;
+  }
+  const hunks = buildHunks(ops, beforeLines, afterLines, limits.context);
+  if (!hunks.length) return "";
+  return `--- ${opts.fromLabel}
++++ ${opts.toLabel}
+${hunks.join("")}`;
+}
+var NO_NEWLINE = "\";
+var NO_NEWLINE_MARK = "\0\0drzl:no-newline";
+function withNoNewlineMark(side) {
+  if (side.newlineAtEnd || !side.lines.length) return side.lines;
+  const marked = side.lines.slice();
+  marked[marked.length - 1] += NO_NEWLINE_MARK;
+  return marked;
+}
+function renderLine(prefix, line, into) {
+  if (line.endsWith(NO_NEWLINE_MARK)) {
+    into.push(prefix + line.slice(0, -NO_NEWLINE_MARK.length));
+    into.push(NO_NEWLINE);
+    return;
+  }
+  into.push(prefix + line);
+}
+function buildHunks(ops, beforeLines, afterLines, context) {
+  const changed = [];
+  ops.forEach((op, i) => {
+    if (op.kind !== "equal") changed.push(i);
+  });
+  if (!changed.length) return [];
+  const ranges = [];
+  for (const i of changed) {
+    const start = Math.max(0, i - context);
+    const end = Math.min(ops.length - 1, i + context);
+    const last = ranges[ranges.length - 1];
+    if (last && start <= last[1] + 1) last[1] = Math.max(last[1], end);
+    else ranges.push([start, end]);
+  }
+  const hunks = [];
+  for (const [start, end] of ranges) {
+    let aStart = -1;
+    let bStart = -1;
+    let aCount = 0;
+    let bCount = 0;
+    const body = [];
+    for (let i = start; i <= end; i++) {
+      const op = ops[i];
+      if (op.kind === "equal" || op.kind === "delete") {
+        if (aStart < 0) aStart = op.a;
+        aCount++;
+      }
+      if (op.kind === "equal" || op.kind === "insert") {
+        if (bStart < 0) bStart = op.b;
+        bCount++;
+      }
+      if (op.kind === "equal") renderLine(" ", beforeLines[op.a], body);
+      else if (op.kind === "delete") renderLine("-", beforeLines[op.a], body);
+      else renderLine("+", afterLines[op.b], body);
+    }
+    const aFrom = aCount === 0 ? 0 : aStart + 1;
+    const bFrom = bCount === 0 ? 0 : bStart + 1;
+    hunks.push(`@@ -${aFrom},${aCount} +${bFrom},${bCount} @@
+${body.join("\n")}
+`);
+  }
+  return hunks;
+}
+
+// src/watch-loop.ts
+var DEFAULT_WATCH_DEBOUNCE_MS = 200;
+function resolveDebounce(value, warn) {
+  if (value === void 0 || value === null || value === "") return DEFAULT_WATCH_DEBOUNCE_MS;
+  const ms = Number(value);
+  if (!Number.isFinite(ms) || ms < 0) {
+    warn(
+      `--debounce ${String(value)} is not a number of milliseconds. Using ${DEFAULT_WATCH_DEBOUNCE_MS}ms.`
+    );
+    return DEFAULT_WATCH_DEBOUNCE_MS;
+  }
+  return ms;
+}
+function createRebuildScheduler(options) {
+  const timers = options.timers ?? {
+    setTimeout: (fn, ms) => setTimeout(fn, ms),
+    clearTimeout: (handle2) => clearTimeout(handle2)
+  };
+  let handle = null;
+  let running = false;
+  let pending = false;
+  const drain = async () => {
+    if (running) {
+      pending = true;
+      return;
+    }
+    running = true;
+    try {
+      await options.run();
+      while (pending) {
+        pending = false;
+        await options.run();
+      }
+    } finally {
+      running = false;
+      pending = false;
+    }
+  };
+  return {
+    trigger() {
+      if (handle !== null) timers.clearTimeout(handle);
+      handle = timers.setTimeout(() => {
+        handle = null;
+        void drain();
+      }, options.debounceMs);
+    },
+    runNow() {
+      return drain();
+    },
+    cancel() {
+      if (handle !== null) timers.clearTimeout(handle);
+      handle = null;
+    },
+    get busy() {
+      return running;
+    }
+  };
+}
+
+// src/init.ts
+import { SchemaAnalyzer } from "@drzl/analyzer";
+import * as fs4 from "fs";
+import * as path4 from "path";
+var INIT_GENERATOR_CHOICES = [
+  { kind: "zod", packageName: "@drzl/generator-zod", label: "Zod validators" },
+  { kind: "valibot", packageName: "@drzl/generator-valibot", label: "Valibot validators" },
+  { kind: "arktype", packageName: "@drzl/generator-arktype", label: "ArkType validators" },
+  { kind: "typebox", packageName: "@drzl/generator-typebox", label: "TypeBox validators" },
+  { kind: "orpc", packageName: "@drzl/generator-orpc", label: "oRPC router" }
+];
+var DEFAULT_GENERATOR_KIND = INIT_GENERATOR_CHOICES[0].kind;
+var ROUTER_KINDS = /* @__PURE__ */ new Set(["orpc"]);
+var SCHEMA_CANDIDATE_STEMS = [
+  "src/db/schema",
+  "src/db/schema/index",
+  "src/db/schemas/index",
+  "src/lib/db/schema",
+  "src/lib/db/schema/index",
+  "src/schema",
+  "src/schema/index",
+  "src/schemas/index",
+  "app/db/schema",
+  "lib/db/schema",
+  "db/schema",
+  "db/schema/index",
+  "drizzle/schema",
+  "schema"
+];
+var CANDIDATE_EXTENSIONS = [".ts", ".js"];
+function schemaCandidates() {
+  const out = [];
+  for (const stem of SCHEMA_CANDIDATE_STEMS) {
+    for (const ext of CANDIDATE_EXTENSIONS) out.push(`${stem}${ext}`);
+  }
+  return out;
+}
+async function classifySchemaCandidate(target) {
+  let analysis;
+  try {
+    analysis = await new SchemaAnalyzer(target).analyze({
+      includeRelations: false,
+      validateConstraints: false
+    });
+  } catch (e) {
+    return { verdict: "unverified", tables: 0, reason: firstLine2(String(e?.message ?? e)) };
+  }
+  if (analysis.tables.length > 0) {
+    return { verdict: "confirmed", tables: analysis.tables.length };
+  }
+  const importError = analysis.issues.find(
+    (i) => i.level === "error" && i.code === "DRZL_ANL_IMPORT"
+  );
+  if (importError)
+    return { verdict: "unverified", tables: 0, reason: firstLine2(importError.message) };
+  return { verdict: "rejected", tables: 0 };
+}
+function firstLine2(message) {
+  return String(message).split("\n")[0].trim();
+}
+async function detectSchema(cwd) {
+  const notes = [];
+  let kitFiles = null;
+  let kitPath;
+  try {
+    const source = await resolveSchemaSource({}, cwd);
+    if (source.source === "drizzle-kit") {
+      kitFiles = source.schema;
+      kitPath = source.drizzleKitConfigPath;
+    }
+  } catch {
+    kitFiles = null;
+  }
+  if (kitFiles && kitPath) {
+    const rel = path4.relative(cwd, kitPath) || path4.basename(kitPath);
+    const report = await classifySchemaCandidate(kitFiles);
+    if (report.verdict === "confirmed" || report.verdict === "unverified") {
+      notes.push(
+        report.verdict === "confirmed" ? `Schema from ${rel} (${kitFiles.length} file${kitFiles.length === 1 ? "" : "s"}, ${report.tables} table${report.tables === 1 ? "" : "s"})` : `Schema from ${rel}, which DRZL could not import yet: ${report.reason}`
+      );
+      return {
+        source: "drizzle-kit",
+        drizzleKitConfig: rel,
+        verdict: report.verdict,
+        tables: report.tables,
+        notes
+      };
+    }
+    notes.push(`${rel} names schema files that declare no Drizzle tables; looking elsewhere.`);
+  }
+  const present = schemaCandidates().filter((c) => fs4.existsSync(path4.resolve(cwd, c)));
+  const unverified = [];
+  for (const file of present) {
+    const report = await classifySchemaCandidate(path4.resolve(cwd, file));
+    if (report.verdict === "confirmed") {
+      notes.push(
+        `Schema found at ${file} (${report.tables} table${report.tables === 1 ? "" : "s"})`
+      );
+      return {
+        source: "convention",
+        schema: file,
+        verdict: "confirmed",
+        tables: report.tables,
+        notes
+      };
+    }
+    if (report.verdict === "unverified") unverified.push({ file, report });
+    else notes.push(`${file} exists but declares no Drizzle tables; not using it.`);
+  }
+  if (unverified.length) {
+    const { file, report } = unverified[0];
+    notes.push(`Schema assumed to be ${file}; DRZL could not import it: ${report.reason}`);
+    return { source: "convention", schema: file, verdict: "unverified", tables: 0, notes };
+  }
+  notes.push(
+    present.length ? "No file DRZL looked at declares any Drizzle tables." : "No drizzle-kit config and no schema in the usual locations."
+  );
+  return { source: "none", tables: 0, notes };
+}
+function generatorLine(kind) {
+  if (kind === "orpc") return `{ kind: 'orpc', template: 'standard', includeRelations: true }`;
+  return `{ kind: '${kind}', path: 'src/validators/${kind}' }`;
+}
+function renderInitConfig(plan) {
+  const lines = [];
+  lines.push(`import type { DrzlConfigInput } from '@drzl/cli/config';`);
+  lines.push("");
+  lines.push("export default {");
+  if (plan.schema) {
+    lines.push(`  schema: '${plan.schema}',`);
+  } else if (plan.schemaSource === "drizzle-kit") {
+    lines.push(`  // No "schema" here on purpose: DRZL reads it from your drizzle-kit config, so`);
+    lines.push(
+      `  // the path is written once. Set "schema" to override it, or "drizzleKit": false`
+    );
+    lines.push(`  // to refuse the fallback.`);
+  } else {
+    lines.push(`  // Set this to your Drizzle schema file, for example 'src/db/schema.ts'. DRZL`);
+    lines.push(`  // found no drizzle-kit config and no schema declaring tables in the usual`);
+    lines.push(`  // locations, and will not name a file that is not there.`);
+    lines.push(`  // schema: 'src/db/schema.ts',`);
+  }
+  const hasRouter = plan.generators.some((k) => ROUTER_KINDS.has(k));
+  if (hasRouter) lines.push(`  outDir: 'src/api',`);
+  lines.push(`  analyzer: { includeRelations: true, validateConstraints: true },`);
+  lines.push("  generators: [");
+  const others = INIT_GENERATOR_CHOICES.filter((c) => !plan.generators.includes(c.kind)).map((c) => `'${c.kind}'`).join(", ");
+  if (others) lines.push(`    // Other kinds this CLI already has installed: ${others}.`);
+  if (hasRouter) {
+    lines.push('    // A second router generator needs its own "path"; they share "outDir".');
+  }
+  for (const kind of plan.generators) lines.push(`    ${generatorLine(kind)},`);
+  lines.push("  ],");
+  lines.push("} satisfies DrzlConfigInput;");
+  return lines.join("\n") + "\n";
+}
+function isInteractive(ctx) {
+  if (ctx.env.CI) return false;
+  return Boolean(ctx.stdin.isTTY) && Boolean(ctx.stdout.isTTY);
+}
+async function ask(rl, question) {
+  const closed = new Promise((resolve4) => rl.once("close", () => resolve4(null)));
+  try {
+    return await Promise.race([rl.question(question), closed]);
+  } catch {
+    return null;
+  }
+}
+async function promptForPlan(args) {
+  const { input, output, detection, cwd } = args;
+  const write = (s) => output.write(s + "\n");
+  let schema = args.schemaFromFlag ?? detection.schema;
+  let schemaSource = args.schemaFromFlag ? "convention" : detection.source;
+  let generators = args.generatorsFromFlag;
+  let endedEarly = false;
+  let readlineModule;
+  try {
+    readlineModule = await import("readline/promises");
+  } catch {
+    return {
+      schema,
+      schemaSource,
+      generators: normalizeGenerators(generators) ?? [DEFAULT_GENERATOR_KIND],
+      endedEarly: true
+    };
+  }
+  const rl = readlineModule.createInterface({ input, output });
+  try {
+    if (args.schemaFromFlag === void 0) {
+      for (const note of detection.notes) write(note);
+      const prompt = detection.source === "drizzle-kit" ? "Schema file, or Enter to keep reading it from your drizzle-kit config: " : detection.schema ? `Schema file [${detection.schema}]: ` : "Schema file (Enter to leave it unset): ";
+      const answer = await ask(rl, prompt);
+      if (answer === null) endedEarly = true;
+      else if (answer.trim()) {
+        const typed = answer.trim();
+        const report = await classifySchemaCandidate(path4.resolve(cwd, typed));
+        if (report.verdict === "confirmed") {
+          write(`  ${typed}: ${report.tables} table${report.tables === 1 ? "" : "s"}`);
+        } else if (report.verdict === "unverified") {
+          write(`  ${typed}: DRZL could not import it (${report.reason}). Using it anyway.`);
+        } else {
+          write(`  ${typed}: no Drizzle tables found in it. Using it anyway.`);
+        }
+        schema = typed;
+        schemaSource = "convention";
+      }
+    }
+    if (generators === void 0 && !endedEarly) {
+      write("What should DRZL generate?");
+      INIT_GENERATOR_CHOICES.forEach((c, i) => write(`  ${i + 1}) ${c.label}`));
+      for (let attempt = 0; attempt < 3; attempt++) {
+        const answer = await ask(rl, `Choice [1, ${INIT_GENERATOR_CHOICES[0].label}]: `);
+        if (answer === null) {
+          endedEarly = true;
+          break;
+        }
+        const raw = answer.trim().toLowerCase();
+        if (!raw) break;
+        const byIndex = Number(raw);
+        const picked = Number.isInteger(byIndex) && byIndex >= 1 && byIndex <= INIT_GENERATOR_CHOICES.length ? INIT_GENERATOR_CHOICES[byIndex - 1] : INIT_GENERATOR_CHOICES.find((c) => c.kind === raw);
+        if (picked) {
+          generators = [picked.kind];
+          break;
+        }
+        write(`  "${answer.trim()}" is not one of the choices.`);
+      }
+    }
+  } finally {
+    rl.close();
+  }
+  return {
+    schema,
+    schemaSource,
+    generators: normalizeGenerators(generators) ?? [DEFAULT_GENERATOR_KIND],
+    endedEarly
+  };
+}
+function normalizeGenerators(kinds) {
+  if (kinds === void 0) return void 0;
+  const known = new Set(INIT_GENERATOR_CHOICES.map((c) => c.kind));
+  for (const k of kinds) {
+    if (!known.has(k)) {
+      throw new Error(
+        `drzl init: "${k}" is not a generator init can scaffold. Choose from ${[...known].join(", ")}. Every other kind is documented in drzl.config; the route generators are optional dependencies and may not be installed.`
+      );
+    }
+  }
+  const picked = INIT_GENERATOR_CHOICES.filter((c) => kinds.includes(c.kind)).map((c) => c.kind);
+  return picked.length ? picked : void 0;
 }
-async function loadGenerator(specifier, load) {
+function parseGeneratorsFlag(value) {
+  if (value === void 0) return void 0;
+  const parts = value.split(",").map((s) => s.trim().toLowerCase()).filter(Boolean);
+  if (!parts.length) throw new Error("drzl init: --generators was given no kinds.");
+  return parts;
+}
+async function runInit(args) {
+  const target = path4.resolve(args.cwd, "drzl.config.ts");
+  const existing = CONFIG_FILE_NAMES.find((name) => fs4.existsSync(path4.resolve(args.cwd, name)));
+  if (existing) {
+    args.error(
+      `drzl init: ${existing} already exists, so nothing was written. Delete it, or edit it by hand; init never overwrites a config, and will not write one that shadows it either.`
+    );
+    return { code: 1 };
+  }
+  let fromFlag;
   try {
-    return await load();
+    fromFlag = normalizeGenerators(parseGeneratorsFlag(args.generatorsFlag));
   } catch (e) {
-    if (isPackageMissing(e, specifier)) throw new GeneratorNotInstalledError(specifier, e);
-    throw e;
+    args.error(String(e?.message ?? e));
+    return { code: 1 };
+  }
+  const detection = await detectSchema(args.cwd);
+  let plan;
+  const interactive = !args.yes && isInteractive({ stdin: args.stdin, stdout: args.stdout, env: args.env });
+  if (interactive) {
+    const result = await promptForPlan({
+      input: args.stdin,
+      output: args.stdout,
+      detection,
+      cwd: args.cwd,
+      schemaFromFlag: args.schemaFlag,
+      generatorsFromFlag: fromFlag
+    });
+    plan = {
+      schema: result.schema,
+      schemaSource: result.schemaSource,
+      generators: result.generators
+    };
+  } else {
+    for (const note of detection.notes) args.log(note);
+    plan = {
+      schema: args.schemaFlag ?? detection.schema,
+      schemaSource: args.schemaFlag ? "convention" : detection.source,
+      generators: fromFlag ?? [DEFAULT_GENERATOR_KIND]
+    };
+    if (args.schemaFlag) {
+      const full = path4.resolve(args.cwd, args.schemaFlag);
+      if (!fs4.existsSync(full)) {
+        args.log(`--schema ${args.schemaFlag} is not there yet. Writing it anyway.`);
+      } else if ((await classifySchemaCandidate(full)).verdict === "rejected") {
+        args.log(`--schema ${args.schemaFlag} declares no Drizzle tables. Writing it anyway.`);
+      }
+    }
+  }
+  try {
+    fs4.writeFileSync(target, renderInitConfig(plan), { flag: "wx" });
+  } catch (e) {
+    if (e?.code === "EEXIST") {
+      args.error(
+        `drzl init: drzl.config.ts already exists, so nothing was written. init never overwrites a config.`
+      );
+      return { code: 1 };
+    }
+    args.error(`drzl init: could not write ${target}: ${e?.message ?? e}`);
+    return { code: 1 };
   }
+  args.log(`Created ${target}`);
+  args.log(`  generators: ${plan.generators.join(", ")}`);
+  if (plan.schema) args.log(`  schema: ${plan.schema}`);
+  else if (plan.schemaSource === "drizzle-kit") args.log("  schema: from your drizzle-kit config");
+  else
+    args.log(
+      '  schema: not set. Fill in "schema" before running `drzl generate`, or add a drizzle-kit config.'
+    );
+  return { code: 0, written: target, plan };
 }
 
 // src/sponsor.ts
-import chalk2 from "chalk";
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from "fs";
-import path2 from "path";
-var CACHE_DIR = path2.join(process.cwd(), "node_modules", ".cache", "@drzl");
-var CACHE_FILE = path2.join(CACHE_DIR, "sponsor-message.json");
+import { existsSync as existsSync3, mkdirSync, readFileSync, writeFileSync as writeFileSync2 } from "fs";
+import path5 from "path";
+var CACHE_DIR = path5.join(process.cwd(), "node_modules", ".cache", "@drzl");
+var CACHE_FILE = path5.join(CACHE_DIR, "sponsor-message.json");
 var DEFAULT_INTERVAL_MS = 1e3 * 60 * 15;
 var shownThisProcess = false;
 var tips = [
@@ -534,17 +2543,19 @@ var tips = [
   "Need JSON Schema or OpenAPI? The json-schema generator emits both, with no runtime dependency.",
   "Use output headers to track generated files and trim noisy diffs."
 ];
-var green = (msg) => chalk2.hex("#6ee7b7")(msg);
-var cyan = (msg) => chalk2.cyan(msg);
-var gray = (msg) => chalk2.gray(msg);
 function maybeShowSponsorMessage({
   reason = "generate",
   minIntervalMs = DEFAULT_INTERVAL_MS,
-  force = false
+  force = false,
+  out = new Output()
 } = {}) {
+  const green = (msg) => out.errStyle.hex("#6ee7b7")(msg);
+  const cyan = (msg) => out.errStyle.cyan(msg);
+  const gray = (msg) => out.errStyle.gray(msg);
   const hideViaEnv = process.env.DRZL_HIDE_SPONSOR?.toLowerCase();
   const hideRequested = hideViaEnv === "1" || hideViaEnv === "true";
   if (hideRequested || process.env.CI && !force || shownThisProcess && !force) return;
+  if (!out.wantsAsides && !force) return;
   try {
     mkdirSync(CACHE_DIR, { recursive: true });
     const payload = readCache();
@@ -559,7 +2570,7 @@ function maybeShowSponsorMessage({
     if (!shouldShow) return;
     shownThisProcess = true;
     const tip = tips[payload.runs % tips.length];
-    console.log(
+    out.stderr.write(
       `
 ${cyan(`\u{1F680} DRZL finished a ${reason} run (#${payload.runs.toLocaleString()}).`)}
 
@@ -567,13 +2578,14 @@ ${green("\u2728 Sponsors keep DRZL shipping. Consider supporting ongoing dev:")}
   ${green("GitHub Sponsors")}  ${gray("\u2192 https://github.com/sponsors/omar-dulaimi")}
 
 ${green("Pro tip:")} ${tip}
+
 `
     );
   } catch {
   }
 }
 function readCache() {
-  if (!existsSync(CACHE_FILE)) {
+  if (!existsSync3(CACHE_FILE)) {
     return { runs: 0 };
   }
   try {
@@ -585,16 +2597,16 @@ function readCache() {
   }
 }
 function writeCache(payload) {
-  writeFileSync(CACHE_FILE, JSON.stringify(payload, null, 2), "utf8");
+  writeFileSync2(CACHE_FILE, JSON.stringify(payload, null, 2), "utf8");
 }
 
 // src/version.ts
 import { readFileSync as readFileSync2 } from "fs";
-import * as path3 from "path";
+import * as path6 from "path";
 import { fileURLToPath } from "url";
 var PACKAGE_NAME = "@drzl/cli";
 function moduleDir() {
-  return path3.dirname(fileURLToPath(import.meta.url));
+  return path6.dirname(fileURLToPath(import.meta.url));
 }
 function readVersionFrom(manifestPath) {
   let raw;
@@ -617,21 +2629,66 @@ function readVersionFrom(manifestPath) {
   return manifest.version;
 }
 function readCliVersion() {
-  return readVersionFrom(path3.join(moduleDir(), "..", "package.json"));
+  return readVersionFrom(path6.join(moduleDir(), "..", "package.json"));
 }
 var CLI_VERSION = readCliVersion();
 
 // src/cli.ts
-function reportGeneratorFailure(kind, e) {
+function reportGeneratorFailure(out, kind, e) {
   if (e instanceof GeneratorNotInstalledError) {
-    console.error(
-      chalk3.red(`The ${kind} generator is not installed.`),
-      chalk3.yellow(`
-Install with: npm install ${e.specifier}`)
+    out.error(`The ${kind} generator is not installed.`);
+    out.hint(`Install with: npm install ${e.specifier}`);
+    return `The ${kind} generator is not installed. Install with: npm install ${e.specifier}`;
+  }
+  const detail = messageOf(e);
+  out.error(`The ${kind} generator failed:`, detail);
+  return `The ${kind} generator failed: ${detail}`;
+}
+function outputFor(opts) {
+  return new Output({ quiet: !!opts.quiet, json: !!opts.json });
+}
+function drzlErrorCode(error, fallback) {
+  return error instanceof ConfigValidationError ? error.code : fallback;
+}
+function reportSchemaProblem(out, command, problem) {
+  if (out.json) out.jsonData(jsonFailure(command, problem.code, problem.message));
+  else {
+    out.error(problem.message);
+    out.hint(problem.hint);
+  }
+  process.exit(EXIT_FAILED);
+}
+var DIFF_FILE_CAP = 20;
+function printCheckDiffs(out, drift) {
+  const shown = drift.slice(0, DIFF_FILE_CAP);
+  for (const d of shown) {
+    const label = displayPath(d.file);
+    const text = unifiedDiff(d.before ?? "", d.after, {
+      fromLabel: `a/${label}`,
+      toLabel: `b/${label}`
+    });
+    if (!text) continue;
+    out.note("");
+    for (const line of text.split("\n")) {
+      if (!line) continue;
+      if (line.startsWith("+++") || line.startsWith("---")) out.note(out.errStyle.bold(line));
+      else if (line.startsWith("@@")) out.note(out.errStyle.cyan(line));
+      else if (line.startsWith("+")) out.note(out.errStyle.green(line));
+      else if (line.startsWith("-")) out.note(out.errStyle.red(line));
+      else out.note(out.errStyle.gray(line));
+    }
+  }
+  if (drift.length > shown.length) {
+    out.note("");
+    out.note(
+      out.errStyle.gray(
+        `${drift.length - shown.length} more file(s) differ. Diffs are capped at ${DIFF_FILE_CAP} files; every drifted file is named in the list above.`
+      )
     );
-    return;
   }
-  console.error(chalk3.red(`The ${kind} generator failed:`), e?.message ?? e);
+}
+function withOutputFlags(command) {
+  return command.option("--json", "write one JSON document to stdout and nothing else", false).option("-q, --quiet", "drop the progress narration on stderr; errors still print", false);
 }
 var program = new Command();
 program.name("drzl").description("DRZL - Drizzle Developer Toolkit").version(CLI_VERSION);
@@ -642,374 +2699,531 @@ Need a template, adapter, or generator DRZL doesn't ship yet?
 \u2192 DM @omardulaimidev on X: https://x.com/omardulaimidev
 `
 );
-program.command("analyze").argument("<schema>", "path to drizzle schema (TS)").option("--relations", "include relations", true).option("--validate", "validate constraints", true).option("--out <file>", "write analysis JSON to file").option("--json", "print JSON to stdout (overrides --out)", false).action(async (schema, opts) => {
+withOutputFlags(
+  program.command("analyze").argument("<schema>", "path to drizzle schema (TS)").option("--relations", "include relations", true).option("--validate", "validate constraints", true).option("--out <file>", "write analysis JSON to file")
+).action(async (schema, opts) => {
+  const out = outputFor(opts);
   try {
-    const analyzer = new SchemaAnalyzer(schema);
-    const spinner = !opts.json ? ora("Analyzing schema...").start() : null;
+    const analyzer = new SchemaAnalyzer2(schema);
+    const spinner = out.spinner("Analyzing schema...");
     const start = Date.now();
     const res = await analyzer.analyze({
       includeRelations: !!opts.relations,
       validateConstraints: !!opts.validate
     });
     const ms = Date.now() - start;
-    const json = JSON.stringify(res, null, 2);
-    if (opts.json) {
-      console.log(json);
-    } else if (opts.out) {
-      const fs2 = await import("fs/promises");
-      await fs2.writeFile(opts.out, json, "utf8");
-      spinner?.succeed(chalk3.green(`Analysis written to ${opts.out} in ${ms}ms`));
+    const unreadable = res.issues.some(
+      (i) => i.level === "error" && (i.code === "DRZL_ANL_NOFILE" || i.code === "DRZL_ANL_IMPORT")
+    );
+    const errors = res.issues.some((i) => i.level === "error");
+    const code = unreadable ? EXIT_FAILED : errors ? EXIT_FINDINGS : EXIT_OK;
+    if (opts.out && !opts.json) {
+      const fs5 = await import("fs/promises");
+      await fs5.writeFile(opts.out, JSON.stringify(res, null, 2), "utf8");
+      spinner.succeed(`Analysis written to ${opts.out} in ${ms}ms`);
     } else {
-      spinner?.succeed(chalk3.green(`Analyzed in ${ms}ms`));
-      console.log(json);
+      spinner.succeed(`Analyzed in ${ms}ms`);
+      const document = opts.json ? { command: "analyze", exitCode: code, ...res } : res;
+      out.data(JSON.stringify(document, null, 2));
     }
-    process.exit(res.issues.some((i) => i.level === "error") ? 2 : 0);
+    process.exit(code);
   } catch (e) {
-    const msg = e?.message ?? String(e);
-    if (opts.json)
-      console.log(JSON.stringify({ event: "error", code: "DRZL_CLI_ANALYZE", message: msg }));
-    else
-      console.error(
-        chalk3.red("Analyze failed (DRZL_CLI_ANALYZE):"),
-        msg,
-        "\nTip: run with --json for structured output."
+    const msg = messageOf(e);
+    if (opts.json) out.jsonData(jsonFailure("analyze", "DRZL_CLI_ANALYZE", msg));
+    else {
+      out.error("Analyze failed (DRZL_CLI_ANALYZE):", msg);
+      out.hint("Tip: run with --json for structured output.");
+    }
+    process.exit(EXIT_FAILED);
+  }
+});
+withOutputFlags(
+  program.command("doctor").description("Report what DRZL cannot type or enforce in your schema, and why").argument("[schema]", "path to drizzle schema (TS); defaults to the schema in drzl.config").option("-c, --config <path>", "path to drzl.config, read when no schema argument is given").option("--strict", "exit 2 when anything is reported", false)
+).action(async (schema, opts) => {
+  const out = outputFor(opts);
+  {
+    try {
+      let target = schema;
+      if (!target) {
+        const cfg = await loadConfig(opts.config, (w) => out.warn(w));
+        if (cfg) target = (await resolveSchemaSource(cfg)).schema;
+      }
+      if (!target) {
+        const msg = "No schema given. Pass a path, or run from a directory with a drzl.config.";
+        if (opts.json) out.jsonData(jsonFailure("doctor", "DRZL_CLI_DOCTOR", msg));
+        else out.error("Doctor failed (DRZL_CLI_DOCTOR):", msg);
+        process.exit(EXIT_FAILED);
+        return;
+      }
+      const analyzer = new SchemaAnalyzer2(target);
+      const analysis = await analyzer.analyze({
+        includeRelations: true,
+        validateConstraints: true
+      });
+      const report = buildDoctorReport(
+        analysis,
+        Array.isArray(target) ? target.join(", ") : target
       );
-    process.exit(1);
+      const unreadable = report.findings.some((f) => f.level === "error");
+      const code = unreadable ? EXIT_FAILED : opts.strict && report.findings.length ? EXIT_FINDINGS : EXIT_OK;
+      if (opts.json)
+        out.data(JSON.stringify({ command: "doctor", exitCode: code, ...report }, null, 2));
+      else out.data(renderDoctorReport(report, out.outStyle));
+      process.exit(code);
+    } catch (e) {
+      const msg = messageOf(e);
+      const code = drzlErrorCode(e, "DRZL_CLI_DOCTOR");
+      if (opts.json) out.jsonData(jsonFailure("doctor", code, msg));
+      else if (e instanceof ConfigValidationError) {
+        out.error(msg);
+      } else {
+        out.error("Doctor failed (DRZL_CLI_DOCTOR):", msg);
+        out.hint("Tip: run with --json for structured output.");
+      }
+      process.exit(EXIT_FAILED);
+    }
   }
 });
-program.command("doctor").description("Report what DRZL cannot type or enforce in your schema, and why").argument("[schema]", "path to drizzle schema (TS); defaults to the schema in drzl.config").option("-c, --config <path>", "path to drzl.config, read when no schema argument is given").option("--json", "print the report as JSON instead of prose", false).option("--strict", "exit 2 when anything is reported", false).action(async (schema, opts) => {
-  try {
-    let target = schema;
-    if (!target) {
-      const cfg = await loadConfig(opts.config);
-      target = cfg?.schema;
+async function explainSchemaSource(opts, out) {
+  if (opts.schema) return { schema: opts.schema, label: opts.schema };
+  const cfg = await loadConfig(opts.config, (w) => out.warn(w));
+  if (cfg) {
+    const source = await resolveSchemaSource(cfg);
+    for (const w of source.warnings) out.warn(w);
+    return {
+      schema: source.schema,
+      label: describeSchemaTarget(source.schema),
+      config: cfg,
+      ...source.source === "drizzle-kit" && source.drizzleKitConfigPath ? { note: `Schema from ${path7.relative(process.cwd(), source.drizzleKitConfigPath)}` } : {}
+    };
+  }
+  const detected = await detectSchema(process.cwd());
+  if (!detected.schema) return void 0;
+  return {
+    schema: detected.schema,
+    label: detected.schema,
+    note: detected.notes[detected.notes.length - 1]
+  };
+}
+withOutputFlags(
+  program.command("explain").description("Show what DRZL understood about one table, and what it did not").argument(
+    "[table]",
+    "the table to explain, by database name, qualified name or export name; omit for the list"
+  ).option("-c, --config <path>", "path to drzl.config, read when --schema is not given").option("-s, --schema <path>", "path to the schema, overriding the config")
+).action(async (tableName, opts) => {
+  const out = outputFor(opts);
+  const fail = (problem) => {
+    if (out.json) out.jsonData(jsonFailure("explain", problem.code, problem.message));
+    else {
+      out.error(problem.message);
+      out.hint(problem.hint);
     }
-    if (!target) {
-      const msg = "No schema given. Pass a path, or run from a directory with a drzl.config.";
-      if (opts.json)
-        console.log(JSON.stringify({ event: "error", code: "DRZL_CLI_DOCTOR", message: msg }));
-      else console.error(chalk3.red("Doctor failed (DRZL_CLI_DOCTOR):"), msg);
-      process.exit(1);
+    process.exit(EXIT_FAILED);
+  };
+  try {
+    const source = await explainSchemaSource(opts, out);
+    if (!source) {
+      fail({
+        code: "DRZL_CFG_001",
+        message: "No schema found (DRZL_CFG_001). There is no drzl.config, no drizzle-kit config, and no schema in the usual locations.",
+        hint: "Pass --schema <path>, or run `drzl init` to write a config."
+      });
       return;
     }
-    const analyzer = new SchemaAnalyzer(target);
-    const analysis = await analyzer.analyze({
+    if (source.note) out.note(out.errStyle.gray(source.note));
+    const spinner = out.spinner("Reading the schema...");
+    const analysis = await new SchemaAnalyzer2(source.schema).analyze({
+      // Both on, for the reason `doctor` turns both on: this command's job is to say everything
+      // that is known, and a relation that appears only under a flag is one a reader would be
+      // told is absent.
       includeRelations: true,
       validateConstraints: true
     });
-    const report = buildDoctorReport(analysis, target);
-    if (opts.json) console.log(JSON.stringify(report, null, 2));
-    else console.log(renderDoctorReport(report));
-    if (report.findings.some((f) => f.level === "error")) {
-      process.exit(1);
-      return;
+    spinner.stop();
+    const problem = schemaLoadFailure(analysis.issues, source.schema, "There is nothing to explain.") ?? nothingToGenerate({
+      schema: source.schema,
+      analyzed: analysis.tables,
+      remaining: analysis.tables,
+      consequence: "There is nothing to explain."
+    });
+    if (problem) reportSchemaProblem(out, "explain", problem);
+    const context = { schema: source.label, dialect: analysis.dialect };
+    if (!tableName) {
+      const tables = summarize(analysis);
+      if (out.json) out.jsonData({ command: "explain", exitCode: EXIT_OK, ...context, tables });
+      else out.data(renderIndex(tables, context, out.outStyle));
+      process.exit(EXIT_OK);
     }
-    process.exit(opts.strict && report.findings.length ? 2 : 0);
+    const match = matchTable(analysis.tables, tableName);
+    if (match.kind === "ambiguous") fail(ambiguousTableProblem(tableName, match.hits));
+    if (match.kind === "none") {
+      fail(noSuchTableProblem(tableName, analysis.tables, match.suggestion));
+    }
+    const cfg = source.config;
+    let keptTables;
+    let keptColumns;
+    if (cfg) {
+      keptTables = filterTables(analysis.tables, cfg).map((t) => qualifiedTableName2(t));
+      try {
+        const narrowed = filterColumns(
+          [match.table],
+          cfg.columns
+        );
+        keptColumns = narrowed.tables[0]?.columns.map((c) => c.name);
+      } catch {
+        keptColumns = void 0;
+      }
+    }
+    const explanation = explainTable(
+      analysis,
+      match,
+      { keptTables, keptColumns }
+    );
+    if (out.json) {
+      out.jsonData({ command: "explain", exitCode: EXIT_OK, ...context, table: explanation });
+    } else {
+      out.data(renderExplanation(explanation, context, out.outStyle));
+    }
+    process.exit(EXIT_OK);
   } catch (e) {
-    const msg = e?.message ?? String(e);
-    if (opts.json)
-      console.log(JSON.stringify({ event: "error", code: "DRZL_CLI_DOCTOR", message: msg }));
-    else
-      console.error(
-        chalk3.red("Doctor failed (DRZL_CLI_DOCTOR):"),
-        msg,
-        "\nTip: run with --json for structured output."
-      );
-    process.exit(1);
+    const msg = messageOf(e);
+    const code = drzlErrorCode(e, "DRZL_CLI_EXPLAIN");
+    if (opts.json) out.jsonData(jsonFailure("explain", code, msg));
+    else if (e instanceof ConfigValidationError) out.error(msg);
+    else {
+      out.error("Explain failed (DRZL_CLI_EXPLAIN):", msg);
+      out.hint("Tip: run with --json for structured output.");
+    }
+    process.exit(EXIT_FAILED);
   }
 });
-program.command("generate").description("Run configured generators (drzl.config.*)").option("-c, --config <path>", "path to drzl.config").option(
-  "--check",
-  "regenerate and fail if the result differs from what is on disk, without changing it"
+withOutputFlags(
+  program.command("generate").description("Run configured generators (drzl.config.*)").option("-c, --config <path>", "path to drzl.config").option("-s, --schema <path>", "path to the schema, overriding the config").option(
+    "--only <kinds>",
+    `run only these generator kinds, comma separated: ${kindList()}`
+  ).option(
+    "--check",
+    "regenerate and fail if the result differs from what is on disk, without changing it"
+  ).option("--dry-run", "report what would be written, and write nothing", false)
 ).action(async (opts) => {
-  try {
-    const cfg = await loadConfig(opts.config);
-    if (!cfg) {
-      console.error(
-        chalk3.red("No config found (DRZL_CFG_001). Create drzl.config.ts or pass --config.")
-      );
-      process.exit(2);
-      return;
-    }
-    const analyzer = new SchemaAnalyzer(cfg.schema);
-    const spinner = ora("Analyzing...").start();
-    const t0 = Date.now();
-    const analysis = await analyzer.analyze({
-      includeRelations: cfg.analyzer.includeRelations,
-      validateConstraints: cfg.analyzer.validateConstraints,
-      includeHeuristicRelations: cfg.analyzer.includeHeuristicRelations
-    });
-    spinner.succeed(`Analysis complete in ${Date.now() - t0}ms`);
-    const narrowed = filterColumns(analysis.tables, cfg.columns);
-    const filterWarnings = tableFilterWarnings(narrowed.tables, cfg);
-    analysis.tables = filterTables(narrowed.tables, cfg);
-    for (const w of [...narrowed.warnings, ...filterWarnings]) console.warn(chalk3.yellow(w));
-    reportWideColumns(analysis.issues);
-    const driftDirs = computeGeneratorOutputDirs(cfg);
-    const driftBefore = opts.check ? await snapshotAll(driftDirs) : null;
-    const progress = new cliProgress.SingleBar(
-      { hideCursor: true },
-      cliProgress.Presets.shades_classic
-    );
-    const total = analysis.tables.length || 1;
-    progress.start(total, 0);
-    const servicesDir = cfg.generators.find((x) => x.kind === "service")?.path ?? "src/services";
-    for (const g of cfg.generators) {
-      if (g.kind === "orpc") {
-        const gen = new ORPCGenerator(analysis);
-        const { files } = await gen.generate({
-          outputDir: cfg.outDir,
-          template: g.template,
-          includeRelations: g.includeRelations,
-          naming: g.naming,
-          outputHeader: g.outputHeader,
-          format: g.format,
-          templateOptions: g.templateOptions,
-          importExtension: g.importExtension,
-          validation: g.validation,
-          // Documented on this generator since it was added and never reachable from a config
-          // file, because the config schema had no such key and zod stripped it in silence.
-          databaseInjection: g.databaseInjection,
-          servicesDir,
-          onProgress: ({ index }) => progress.update(index)
-        });
-        progress.stop();
-        ora().succeed(chalk3.green(`Generated (${g.kind}): ${files.length} files`));
-        files.forEach((f) => console.log("  -", chalk3.cyan(f)));
-      } else if (g.kind === "trpc") {
-        try {
-          const { TRPCGenerator } = await loadGenerator(
-            "@drzl/generator-trpc",
-            () => import("./dist-XBGVORL3.js")
-          );
-          const gen = new TRPCGenerator(analysis);
-          const { files } = await gen.generate({
-            ...trpcOptions(g, cfg, servicesDir),
-            onProgress: ({ index }) => progress.update(index)
-          });
-          progress.stop();
-          ora().succeed(chalk3.green(`Generated (trpc): ${files.length} files`));
-          files.forEach((f) => console.log("  -", chalk3.cyan(f)));
-        } catch (e) {
-          progress.stop();
-          reportGeneratorFailure(g.kind, e);
-          process.exit(1);
+  const out = outputFor(opts);
+  const planning = !!opts.check || !!opts.dryRun;
+  const emitted = [];
+  const warnings = [];
+  const warn = (text) => {
+    warnings.push(text);
+    out.warn(text);
+  };
+  {
+    try {
+      const only = parseOnly(opts.only);
+      let cfg = await loadConfig(opts.config, warn);
+      if (!cfg && only) {
+        cfg = configFromKinds([...only], opts.schema, warn);
+      }
+      if (!cfg) {
+        const msg = "No config found (DRZL_CFG_001). Create drzl.config.ts or pass --config.";
+        if (opts.json) out.jsonData(jsonFailure("generate", "DRZL_CFG_001", msg));
+        else {
+          out.error(msg);
+          out.hint("Or run one generator with no config: drzl generate --schema <path> --only <kind>.");
         }
-      } else if (g.kind === "service") {
-        try {
-          const { ServiceGenerator } = await loadGenerator(
-            "@drzl/generator-service",
-            () => import("@drzl/generator-service")
-          );
-          const gen = new ServiceGenerator(analysis);
-          const target = g.path ?? "src/services";
-          const files = await gen.generate({
-            outDir: target,
-            outputHeader: g.outputHeader,
-            format: g.format,
-            dataAccess: g.dataAccess,
-            dbImportPath: g.dbImportPath,
-            schemaImportPath: g.schemaImportPath,
-            importExtension: g.importExtension,
-            // The other half of `databaseInjection`. A router generator in injection mode
-            // emits `Service.getById(ctx.db, id)`, and only a service generated in the same
-            // mode has a `db` parameter to receive it. This branch never passed the option, so
-            // the two halves of one generated project disagreed about the signature.
-            databaseInjection: g.databaseInjection
-          });
-          progress.stop();
-          ora().succeed(chalk3.green(`Generated (service): ${files.length} files`));
-          files.forEach((f) => console.log("  -", chalk3.cyan(f)));
-        } catch (e) {
-          progress.stop();
-          reportGeneratorFailure(g.kind, e);
-          process.exit(1);
+        process.exit(EXIT_FAILED);
+        return;
+      }
+      if (opts.schema) {
+        const { drizzleKit: _fromConfig, ...rest } = cfg;
+        cfg = { ...rest, schema: opts.schema };
+      }
+      const nothingSelected = emptySelectionMessage(only, cfg.generators);
+      if (nothingSelected) {
+        if (opts.json) out.jsonData(jsonFailure("generate", "DRZL_CLI_ONLY", nothingSelected));
+        else {
+          out.error(nothingSelected);
+          out.hint('Add it to "generators" in your config, or name a kind that is already there.');
         }
-      } else if (g.kind === "zod") {
-        try {
-          const { ZodGenerator } = await loadGenerator(
-            "@drzl/generator-zod",
-            () => import("@drzl/generator-zod")
-          );
-          const gen = new ZodGenerator(analysis);
-          const target = g.path ?? "src/validators/zod";
-          const files = await gen.generate(
-            validationOptions(g, cfg, target, { schemaTypes: true, meta: true })
-          );
-          progress.stop();
-          ora().succeed(chalk3.green(`Generated (zod): ${files.length} files`));
-          files.forEach((f) => console.log("  -", chalk3.cyan(f)));
-        } catch (e) {
-          progress.stop();
-          reportGeneratorFailure(g.kind, e);
-          process.exit(1);
+        process.exit(EXIT_FAILED);
+        return;
+      }
+      const source = await resolveSchemaSource(cfg);
+      for (const w of source.warnings) warn(w);
+      if (!cfg.schema && Array.isArray(source.schema) && source.schema.length === 1) {
+        cfg = { ...cfg, schema: source.schema[0] };
+      }
+      if (source.source === "drizzle-kit") {
+        const n = source.schema.length;
+        out.note(
+          out.errStyle.gray(
+            `Schema from ${path7.relative(process.cwd(), source.drizzleKitConfigPath)} (${n} file${n === 1 ? "" : "s"})`
+          )
+        );
+      }
+      const analyzer = new SchemaAnalyzer2(source.schema);
+      const spinner = out.spinner("Analyzing...");
+      const t0 = Date.now();
+      const analysis = await analyzer.analyze({
+        includeRelations: cfg.analyzer.includeRelations,
+        validateConstraints: cfg.analyzer.validateConstraints,
+        includeHeuristicRelations: cfg.analyzer.includeHeuristicRelations
+      });
+      const loadFailure = schemaLoadFailure(analysis.issues, source.schema);
+      if (loadFailure) {
+        spinner.stop();
+        reportSchemaProblem(out, "generate", loadFailure);
+      }
+      spinner.succeed(`Analysis complete in ${Date.now() - t0}ms`);
+      const dialectWarning = dialectMismatchWarning({
+        configPath: source.drizzleKitConfigPath ?? "",
+        declared: source.drizzleKitDialect,
+        analyzed: analysis.dialect
+      });
+      if (dialectWarning) warn(dialectWarning);
+      const narrowed = filterColumns(analysis.tables, cfg.columns);
+      const filterWarnings = tableFilterWarnings(narrowed.tables, cfg);
+      analysis.tables = filterTables(narrowed.tables, cfg);
+      for (const w of [...narrowed.warnings, ...filterWarnings]) warn(w);
+      for (const w of wideColumnWarning(analysis.issues)) warn(w);
+      const empty = nothingToGenerate({
+        schema: source.schema,
+        analyzed: narrowed.tables,
+        remaining: analysis.tables
+      });
+      if (empty) reportSchemaProblem(out, "generate", empty);
+      const outputDirs = computeGeneratorOutputDirs(cfg);
+      const existing = planning ? await snapshotAll(outputDirs) : void 0;
+      const plan = new EmitPlan({ write: !planning, existing });
+      const total = analysis.tables.length || 1;
+      const progress = out.progress(total);
+      const generated = (kind, files) => {
+        progress.stop();
+        const missed = plan.unrecorded(files);
+        if (missed.length && planning) {
+          const message = `The ${kind} generator wrote ${missed.length} file(s) directly instead of reporting them, so this run could not be a preview. Update @drzl/generator-${kind} to a version that supports --dry-run. First file: ${displayPath(missed[0])}`;
+          if (opts.json) out.jsonData(jsonFailure("generate", "DRZL_GEN_003", message));
+          else out.error(message);
+          process.exit(EXIT_FAILED);
         }
-      } else if (g.kind === "valibot") {
-        try {
-          const { ValibotGenerator } = await loadGenerator(
-            "@drzl/generator-valibot",
-            () => import("@drzl/generator-valibot")
-          );
-          const gen = new ValibotGenerator(analysis);
-          const target = g.path ?? "src/validators/valibot";
-          const files = await gen.generate(
-            validationOptions(g, cfg, target, { schemaTypes: true })
-          );
-          progress.stop();
-          ora().succeed(chalk3.green(`Generated (valibot): ${files.length} files`));
-          files.forEach((f) => console.log("  -", chalk3.cyan(f)));
-        } catch (e) {
-          progress.stop();
-          reportGeneratorFailure(g.kind, e);
-          process.exit(1);
+        const verdicts = plan.verdictsFor(files).filter(Boolean);
+        emitted.push({
+          kind,
+          files,
+          changes: verdicts.map((v) => ({ file: v.file, status: v.verdict }))
+        });
+        if (opts.json) return;
+        if (out.quiet) return;
+        out.succeed(
+          out.errStyle.green(
+            `${planning ? "Would write" : "Generated"} (${kind}): ${files.length} files`
+          ) + out.errStyle.gray(` (${describeCounts(plan.counts(files))})`)
+        );
+        for (const v of verdicts) {
+          if (opts.check) break;
+          if (v.verdict === "unchanged") continue;
+          const mark = v.verdict === "created" ? "+" : "~";
+          out.note("  " + out.errStyle.cyan(mark + " " + displayPath(v.file)));
         }
-      } else if (g.kind === "arktype") {
+        for (const f of files) out.data("  - " + out.outStyle.cyan(f));
+      };
+      const failGenerator = (kind, e) => {
+        progress.stop();
+        const message = reportGeneratorFailure(out, kind, e);
+        if (opts.json) out.jsonData(jsonFailure("generate", "DRZL_GEN_002", message));
+        process.exit(EXIT_FAILED);
+      };
+      const servicesDir = resolveServicesDir(cfg);
+      for (const g of selectGenerators(cfg.generators, only)) {
+        progress.start();
+        const entry = GENERATOR_BY_KIND.get(g.kind);
+        if (!entry) continue;
         try {
-          const { ArkTypeGenerator } = await loadGenerator(
-            "@drzl/generator-arktype",
-            () => import("@drzl/generator-arktype")
-          );
-          const gen = new ArkTypeGenerator(analysis);
-          const target = g.path ?? "src/validators/arktype";
-          const files = await gen.generate(
-            validationOptions(g, cfg, target, { schemaTypes: false })
-          );
-          progress.stop();
-          ora().succeed(chalk3.green(`Generated (arktype): ${files.length} files`));
-          files.forEach((f) => console.log("  -", chalk3.cyan(f)));
+          const files = await runGenerator(entry, g, cfg, {
+            analysis,
+            servicesDir,
+            fileSink: plan,
+            onProgress: ({ index }) => progress.update(index)
+          });
+          generated(g.kind, files);
         } catch (e) {
-          progress.stop();
-          reportGeneratorFailure(g.kind, e);
-          process.exit(1);
+          failGenerator(g.kind, e);
         }
-      } else if (g.kind === "json-schema") {
-        try {
-          const { JsonSchemaGenerator } = await loadGenerator(
-            "@drzl/generator-json-schema",
-            () => import("./dist-K6N4F3XW.js")
-          );
-          const gen = new JsonSchemaGenerator(analysis);
-          const target = g.path ?? "src/validators/json-schema";
-          const files = await gen.generate(jsonSchemaOptions(g, cfg, target));
-          progress.stop();
-          ora().succeed(chalk3.green(`Generated (json-schema): ${files.length} files`));
-          files.forEach((f) => console.log("  -", chalk3.cyan(f)));
-        } catch (e) {
-          progress.stop();
-          reportGeneratorFailure(g.kind, e);
-          process.exit(1);
+      }
+      const generatorsDocument = () => emitted.map((e) => ({
+        kind: e.kind,
+        files: e.files,
+        changes: e.changes.map((c) => ({ file: displayPath(c.file), status: c.status }))
+      }));
+      if (planning) {
+        const wrote = await verifyNothingWasWritten(outputDirs, existing);
+        if (wrote.length) {
+          const message = `${wrote.length} file(s) were written by a run that promised to write none, and have been restored. This means an installed generator package is older than this CLI. Update your @drzl/generator-* packages. First file: ${displayPath(wrote[0])}`;
+          if (opts.json) out.jsonData(jsonFailure("generate", "DRZL_GEN_003", message));
+          else out.error(message);
+          process.exit(EXIT_FAILED);
         }
-      } else if (g.kind === "typebox") {
-        try {
-          const { TypeBoxGenerator } = await loadGenerator(
-            "@drzl/generator-typebox",
-            () => import("@drzl/generator-typebox")
-          );
-          const gen = new TypeBoxGenerator(analysis);
-          const target = g.path ?? "src/validators/typebox";
-          const files = await gen.generate(
-            validationOptions(g, cfg, target, {
-              schemaTypes: true,
-              standardSchema: true
-            })
-          );
-          progress.stop();
-          ora().succeed(chalk3.green(`Generated (typebox): ${files.length} files`));
-          files.forEach((f) => console.log("  -", chalk3.cyan(f)));
-        } catch (e) {
-          progress.stop();
-          reportGeneratorFailure(g.kind, e);
-          process.exit(1);
+      }
+      if (opts.check) {
+        const drift = pendingChanges(plan);
+        const upToDate = drift.length === 0;
+        const code = upToDate ? EXIT_OK : EXIT_FINDINGS;
+        if (opts.json) {
+          out.jsonData({
+            ok: true,
+            command: "generate",
+            exitCode: code,
+            check: {
+              upToDate,
+              drift: drift.map((d, i) => ({
+                file: displayPath(d.file),
+                status: driftStatusOf(d.verdict),
+                // Item 81. Beyond the cap the entry is still here with its status, and only the
+                // diff is absent, so a machine reading this never loses a file.
+                diff: i < DIFF_FILE_CAP ? unifiedDiff(d.before ?? "", d.after, {
+                  fromLabel: `a/${displayPath(d.file)}`,
+                  toLabel: `b/${displayPath(d.file)}`
+                }) : null
+              })),
+              diffFileCap: DIFF_FILE_CAP
+            },
+            generators: generatorsDocument(),
+            warnings
+          });
+          process.exit(code);
         }
-      } else if (g.kind === "effect") {
-        try {
-          const { EffectGenerator } = await loadGenerator(
-            "@drzl/generator-effect",
-            () => import("./dist-WHAW3AMQ.js")
-          );
-          const gen = new EffectGenerator(analysis);
-          const target = g.path ?? "src/validators/effect";
-          const files = await gen.generate(
-            validationOptions(g, cfg, target, { schemaTypes: true })
-          );
-          progress.stop();
-          ora().succeed(chalk3.green(`Generated (effect): ${files.length} files`));
-          files.forEach((f) => console.log("  -", chalk3.cyan(f)));
-        } catch (e) {
-          progress.stop();
-          reportGeneratorFailure(g.kind, e);
-          process.exit(1);
+        if (!upToDate) {
+          out.error(`
+Generated output is out of date (${drift.length} file(s)):`);
+          for (const d of drift) {
+            const status = driftStatusOf(d.verdict);
+            const mark = status === "added" ? "+" : "~";
+            out.error(
+              `  ${mark} ${out.errStyle.yellow(status.padEnd(8))} ${displayPath(d.file)}`
+            );
+          }
+          printCheckDiffs(out, drift);
+          out.hint("\nRun `drzl generate` and commit the result. Nothing was written by this check.");
+          process.exit(code);
         }
+        out.succeed(out.errStyle.green("Generated output is up to date."));
+        process.exit(code);
       }
-    }
-    if (driftBefore) {
-      const after = await snapshotAll(driftDirs);
-      const drift = diffSnapshots(driftBefore, after);
-      await restoreSnapshot(driftBefore, after);
-      if (drift.length) {
-        console.error(chalk3.red(`
-Generated output is out of date (${drift.length} file(s)):`));
-        for (const d of drift) {
-          const mark = d.status === "added" ? "+" : d.status === "removed" ? "-" : "~";
-          console.error(
-            `  ${mark} ${chalk3.yellow(d.status.padEnd(8))} ${path4.relative(process.cwd(), d.file)}`
-          );
-        }
-        console.error(
-          chalk3.dim(
-            "\nRun `drzl generate` and commit the result. Nothing was written by this check."
-          )
+      if (opts.json) {
+        out.jsonData({
+          ok: true,
+          command: "generate",
+          exitCode: EXIT_OK,
+          check: null,
+          dryRun: !!opts.dryRun,
+          generators: generatorsDocument(),
+          warnings
+        });
+        return;
+      }
+      if (opts.dryRun) {
+        const counts = plan.counts();
+        out.succeed(
+          out.errStyle.green(`Dry run: ${counts.total} file(s) would be written`) + out.errStyle.gray(` (${describeCounts(counts)}). Nothing was written.`)
         );
-        process.exit(1);
+        process.exit(EXIT_OK);
       }
-      console.log(chalk3.green("Generated output is up to date."));
-      return;
-    }
-    if (cfg.generators.length) {
-      maybeShowSponsorMessage({ reason: "generate" });
+      if (cfg.generators.length) {
+        maybeShowSponsorMessage({ reason: "generate", out });
+      }
+    } catch (e) {
+      const msg = messageOf(e);
+      const code = drzlErrorCode(e, "DRZL_GEN_001");
+      if (e instanceof KindSelectionError) {
+        if (opts.json) out.jsonData(jsonFailure("generate", e.code, msg));
+        else {
+          out.error(msg);
+          if (e.hint) out.hint(e.hint);
+        }
+        process.exit(EXIT_FAILED);
+      }
+      if (opts.json) out.jsonData(jsonFailure("generate", code, msg));
+      else if (e instanceof ConfigValidationError) {
+        out.error(msg);
+      } else {
+        out.error("Generate failed (DRZL_GEN_001):", msg);
+        out.hint("Tip: check your drzl.config.ts and template path.");
+      }
+      process.exit(EXIT_FAILED);
     }
-  } catch (e) {
-    console.error(
-      chalk3.red("Generate failed (DRZL_GEN_001):"),
-      e?.message ?? e,
-      "\nTip: check your drzl.config.ts and template path."
-    );
-    process.exit(1);
   }
 });
-program.command("generate:orpc").argument("<schema>", "path to drizzle schema (TS)").option("-o, --outDir <dir>", "output directory", "src/api").option("--template <name>", "template name", "standard").option("--includeRelations", "include relation endpoints").action(async (schema, opts) => {
+function schemaProblemFor(analysis, schema) {
+  return schemaLoadFailure(analysis.issues, schema) ?? nothingToGenerate({ schema, analyzed: analysis.tables, remaining: analysis.tables });
+}
+function deprecationNotice(command, kind, schema, cmd) {
+  const replacement = `drzl generate --schema ${schema} --only ${kind}`;
+  const CONFIG_KEYS = {
+    outDir: "outDir",
+    template: "template",
+    includeRelations: "includeRelations",
+    servicesDir: "the service generator's path"
+  };
+  const moved = Object.keys(CONFIG_KEYS).filter(
+    (name) => cmd.getOptionValueSource(name) === "cli"
+  );
+  const tail = moved.length ? ` (${moved.map((name) => CONFIG_KEYS[name]).join(", ")} ${moved.length === 1 ? "moves" : "move"} into drzl.config.ts)` : "";
+  return `${command} is deprecated and will be removed in 5.0. Run this instead: ${replacement}${tail}`;
+}
+withOutputFlags(
+  program.command("generate:orpc").description("Deprecated. Use `drzl generate --schema <path> --only orpc`").argument("<schema>", "path to drizzle schema (TS)").option("-o, --outDir <dir>", "output directory", "src/api").option("--template <name>", "template name", "standard").option("--includeRelations", "include relation endpoints")
+).action(async (schema, opts, cmd) => {
+  const out = outputFor(opts);
+  out.warn(deprecationNotice("generate:orpc", "orpc", schema, cmd));
   try {
-    const analyzer = new SchemaAnalyzer(schema);
+    const analyzer = new SchemaAnalyzer2(schema);
     const analysis = await analyzer.analyze({
       includeRelations: !!opts.includeRelations,
       validateConstraints: true
     });
-    const gen = new ORPCGenerator(analysis);
-    const { files } = await gen.generate({
+    const problem = schemaProblemFor(analysis, schema);
+    if (problem) reportSchemaProblem(out, "generate:orpc", problem);
+    const files = await runGeneratorWithOptions(entryFor("orpc"), analysis, {
       outputDir: opts.outDir,
       template: opts.template,
       includeRelations: !!opts.includeRelations
     });
-    console.log(chalk3.green(`Generated:`), files.map((f) => chalk3.cyan(f)).join(", "));
-    maybeShowSponsorMessage({ reason: "generate:orpc" });
+    if (opts.json) {
+      out.jsonData({
+        ok: true,
+        command: "generate:orpc",
+        exitCode: EXIT_OK,
+        generators: [{ kind: "orpc", files }]
+      });
+      return;
+    }
+    if (!out.quiet) {
+      out.data(out.outStyle.green("Generated:") + " " + files.map((f) => out.outStyle.cyan(f)).join(", "));
+    }
+    maybeShowSponsorMessage({ reason: "generate:orpc", out });
   } catch (e) {
-    console.error(chalk3.red("Generate orpc failed:"), e?.message ?? e);
-    process.exit(1);
+    let message;
+    if (e instanceof GeneratorNotInstalledError) {
+      message = reportGeneratorFailure(out, "orpc", e);
+    } else {
+      message = messageOf(e);
+      out.error("Generate orpc failed:", message);
+    }
+    if (opts.json) out.jsonData(jsonFailure("generate:orpc", "DRZL_CLI_ORPC", message));
+    process.exit(EXIT_FAILED);
   }
 });
-program.command("generate:trpc").argument("<schema>", "path to drizzle schema (TS)").option("-o, --outDir <dir>", "output directory", "src/api").option("--template <name>", "standard | service", "standard").option("--includeRelations", "include relation endpoints").option("--servicesDir <dir>", "where the service generator writes", "src/services").action(async (schema, opts) => {
+withOutputFlags(
+  program.command("generate:trpc").description("Deprecated. Use `drzl generate --schema <path> --only trpc`").argument("<schema>", "path to drizzle schema (TS)").option("-o, --outDir <dir>", "output directory", "src/api").option("--template <name>", "standard | service", "standard").option("--includeRelations", "include relation endpoints").option("--servicesDir <dir>", "where the service generator writes", "src/services")
+).action(async (schema, opts, cmd) => {
+  const out = outputFor(opts);
+  out.warn(deprecationNotice("generate:trpc", "trpc", schema, cmd));
   try {
-    const analyzer = new SchemaAnalyzer(schema);
+    const analyzer = new SchemaAnalyzer2(schema);
     const analysis = await analyzer.analyze({
       includeRelations: !!opts.includeRelations,
       validateConstraints: true
     });
-    const { TRPCGenerator } = await loadGenerator(
-      "@drzl/generator-trpc",
-      () => import("./dist-XBGVORL3.js")
-    );
-    const gen = new TRPCGenerator(analysis);
-    const { files } = await gen.generate({
+    const problem = schemaProblemFor(analysis, schema);
+    if (problem) reportSchemaProblem(out, "generate:trpc", problem);
+    const files = await runGeneratorWithOptions(entryFor("trpc"), analysis, {
       outputDir: opts.outDir,
       template: opts.template,
       includeRelations: !!opts.includeRelations,
@@ -1017,27 +3231,95 @@ program.command("generate:trpc").argument("<schema>", "path to drizzle schema (T
       // cannot become the branch that forgets it.
       servicesDir: opts.servicesDir
     });
-    console.log(chalk3.green(`Generated:`), files.map((f) => chalk3.cyan(f)).join(", "));
-    maybeShowSponsorMessage({ reason: "generate:trpc" });
+    if (opts.json) {
+      out.jsonData({
+        ok: true,
+        command: "generate:trpc",
+        exitCode: EXIT_OK,
+        generators: [{ kind: "trpc", files }]
+      });
+      return;
+    }
+    if (!out.quiet) {
+      out.data(
+        out.outStyle.green("Generated:") + " " + files.map((f) => out.outStyle.cyan(f)).join(", ")
+      );
+    }
+    maybeShowSponsorMessage({ reason: "generate:trpc", out });
   } catch (e) {
-    reportGeneratorFailure("trpc", e);
-    process.exit(1);
+    const message = reportGeneratorFailure(out, "trpc", e);
+    if (opts.json) out.jsonData(jsonFailure("generate:trpc", "DRZL_CLI_TRPC", message));
+    process.exit(EXIT_FAILED);
   }
 });
-program.command("watch").description("Watch schema and regenerate on changes").option("-c, --config <path>", "path to drzl.config").option("--pipeline <name>", "all | analyze | generate-orpc | generate-trpc", "all").option("--debounce <ms>", "debounce ms", "200").option("--json", "emit JSON logs", false).option("--poll", "force polling (helps WSL/Docker/remote FS)", false).action(async (opts) => {
-  let cfg = await loadConfig(opts.config);
-  if (!cfg) {
-    console.error(chalk3.red("No config found. Create drzl.config.ts or pass --config."));
-    process.exit(2);
+program.command("watch").description("Watch schema and regenerate on changes").option("-c, --config <path>", "path to drzl.config").option(
+  "--only <kinds>",
+  `rebuild only these generator kinds, comma separated: ${kindList()}`
+).option(
+  "--pipeline <name>",
+  "all | analyze | generate-<kind>, the older spelling of --only",
+  "all"
+).option("--debounce <ms>", "wait this long after the last change before rebuilding", "200").option("--clear", "clear the terminal before each rebuild", false).option("--json", "emit JSON logs", false).option("-q, --quiet", "drop the progress narration on stderr; errors still print", false).option("--poll", "force polling (helps WSL/Docker/remote FS)", false).action(async (opts) => {
+  const out = outputFor(opts);
+  let selection;
+  try {
+    selection = resolveWatchSelection(opts);
+  } catch (e) {
+    if (e instanceof KindSelectionError) {
+      if (opts.json) out.jsonData(jsonFailure("watch", e.code, e.message));
+      else {
+        out.error(e.message);
+        if (e.hint) out.hint(e.hint);
+      }
+    } else out.error(messageOf(e));
+    process.exit(EXIT_FAILED);
+    return;
+  }
+  const reportWatchProblem = (problem) => {
+    if (opts.json) {
+      out.jsonData({ event: "error", code: problem.code, message: problem.message });
+      return;
+    }
+    out.error(problem.message);
+    out.hint(problem.hint);
+  };
+  const clearScreen = () => {
+    if (!opts.clear || opts.json || out.quiet) return;
+    if (!out.stderr.isTTY) return;
+    out.stderr.write("\x1B[2J\x1B[3J\x1B[H");
+  };
+  let loaded;
+  try {
+    loaded = await loadConfig(opts.config, (w) => out.warn(w));
+  } catch (e) {
+    out.error(messageOf(e));
+    process.exit(EXIT_FAILED);
     return;
   }
-  const abs = (p) => path4.resolve(process.cwd(), p);
+  if (!loaded) {
+    out.error("No config found (DRZL_CFG_001). Create drzl.config.ts or pass --config.");
+    process.exit(EXIT_FAILED);
+    return;
+  }
+  let cfg = loaded;
+  const abs = (p) => path7.resolve(process.cwd(), p);
   const isInside = (child, parent) => {
-    const rel = path4.relative(parent, child);
-    return !!rel && !rel.startsWith("..") && !path4.isAbsolute(rel);
+    const rel = path7.relative(parent, child);
+    return !!rel && !rel.startsWith("..") && !path7.isAbsolute(rel);
   };
+  let source;
+  try {
+    source = await resolveSchemaSource(cfg);
+  } catch (e) {
+    out.error(messageOf(e));
+    process.exit(EXIT_FAILED);
+    return;
+  }
+  for (const w of source.warnings) out.warn(w);
   const ignoredOutDirs = new Set(computeGeneratorOutputDirs(cfg).map(abs));
-  const currentTargets = new Set(computeWatchTargets(cfg).map(abs));
+  const currentTargets = new Set(
+    computeWatchTargets(cfg, process.cwd(), source).map(abs)
+  );
   const syncWatcherTargets = (watcher2, next) => {
     const add = [];
     const del = [];
@@ -1059,7 +3341,7 @@ program.command("watch").description("Watch schema and regenerate on changes").o
       if (full === dir || isInside(full, dir)) return true;
     }
     if (stats?.isDirectory()) return false;
-    const ext = path4.extname(full);
+    const ext = path7.extname(full);
     if (!ext) return false;
     return !WATCHED_EXTENSIONS.has(ext);
   };
@@ -1070,7 +3352,7 @@ program.command("watch").description("Watch schema and regenerate on changes").o
     ignored: ignoredFn
   });
   const logTrigger = (type, file) => {
-    if (opts.json) console.log(JSON.stringify({ event: "trigger", type, file }));
+    if (opts.json) out.jsonData({ event: "trigger", type, file });
   };
   watcher.on("add", (p) => {
     logTrigger("add", p);
@@ -1083,264 +3365,127 @@ program.command("watch").description("Watch schema and regenerate on changes").o
     trigger(p);
   });
   let lastFiles = [];
+  const watchGenerated = (kind, files) => {
+    if (opts.json) {
+      out.jsonData({ event: "generate_complete", kind, files });
+      return;
+    }
+    out.succeed(
+      out.errStyle.green(`Generated (${kind}): ${files.length} files`) + (files.length ? " " + files.map((f) => out.errStyle.cyan(f)).join(", ") : "")
+    );
+  };
   const run = async () => {
     try {
-      const reloaded = await loadConfig(opts.config);
+      const reloaded = await loadConfig(opts.config, (w) => out.warn(w));
       if (!reloaded) throw new Error("Config disappeared during watch.");
       cfg = reloaded;
+      source = await resolveSchemaSource(cfg);
+      if (!cfg.schema && Array.isArray(source.schema) && source.schema.length === 1) {
+        cfg = { ...cfg, schema: source.schema[0] };
+      }
       rebuildIgnoreDirsFrom(cfg);
-      const nextTargets = new Set(computeWatchTargets(cfg).map(abs));
+      const nextTargets = new Set(
+        computeWatchTargets(cfg, process.cwd(), source).map(abs)
+      );
       syncWatcherTargets(watcher, nextTargets);
-      if (!opts.json) console.clear();
+      clearScreen();
       if (opts.json) {
-        console.log(
-          JSON.stringify({
-            event: "watch_config_applied",
-            targets: Array.from(currentTargets),
-            ignored: Array.from(ignoredOutDirs)
-          })
-        );
+        out.jsonData({
+          event: "watch_config_applied",
+          targets: Array.from(currentTargets),
+          ignored: Array.from(ignoredOutDirs)
+        });
       }
-      const analyzer = new SchemaAnalyzer(cfg.schema);
+      for (const w of source.warnings) out.warn(w);
+      const analyzer = new SchemaAnalyzer2(source.schema);
       const analysis = await analyzer.analyze({
         includeRelations: cfg.analyzer.includeRelations,
         validateConstraints: cfg.analyzer.validateConstraints,
         includeHeuristicRelations: cfg.analyzer.includeHeuristicRelations
       });
+      const dialectWarning = dialectMismatchWarning({
+        configPath: source.drizzleKitConfigPath ?? "",
+        declared: source.drizzleKitDialect,
+        analyzed: analysis.dialect
+      });
+      if (dialectWarning) out.warn(dialectWarning);
+      const loadFailure = schemaLoadFailure(analysis.issues, source.schema);
+      if (loadFailure) {
+        reportWatchProblem(loadFailure);
+        return;
+      }
       const narrowed = filterColumns(analysis.tables, cfg.columns);
       const filterWarnings = tableFilterWarnings(narrowed.tables, cfg);
       analysis.tables = filterTables(narrowed.tables, cfg);
-      if (!opts.json)
-        for (const w of [...narrowed.warnings, ...filterWarnings]) console.warn(chalk3.yellow(w));
-      if (!opts.json) reportWideColumns(analysis.issues);
-      if (opts.pipeline === "analyze") {
+      for (const w of [...narrowed.warnings, ...filterWarnings]) out.warn(w);
+      for (const w of wideColumnWarning(analysis.issues)) out.warn(w);
+      if (selection.analyzeOnly) {
         if (opts.json) {
-          console.log(
-            JSON.stringify({
-              event: "analyze_complete",
-              issues: analysis.issues,
-              tables: analysis.tables.length
-            })
-          );
+          out.jsonData({
+            event: "analyze_complete",
+            issues: analysis.issues,
+            tables: analysis.tables.length
+          });
         } else {
-          console.log(chalk3.green("Analyze complete."));
+          out.succeed("Analyze complete.");
         }
         return;
       }
+      const empty = nothingToGenerate({
+        schema: source.schema,
+        analyzed: narrowed.tables,
+        remaining: analysis.tables
+      });
+      if (empty) {
+        reportWatchProblem(empty);
+        return;
+      }
       const newFiles = [];
-      const servicesDir = cfg.generators.find((x) => x.kind === "service")?.path ?? "src/services";
-      const PIPELINE_KINDS = {
-        "generate-orpc": "orpc",
-        "generate-trpc": "trpc"
-      };
-      for (const g of cfg.generators) {
-        if (opts.pipeline !== "all" && PIPELINE_KINDS[opts.pipeline] !== g.kind) {
-          continue;
+      const servicesDir = resolveServicesDir(cfg);
+      const unmatched = emptySelectionMessage(selection.kinds, cfg.generators);
+      if (unmatched) {
+        if (opts.json) out.jsonData({ event: "error", code: "DRZL_CLI_ONLY", message: unmatched });
+        else {
+          out.error(unmatched);
+          out.hint('Add it to "generators" in your config, or name a kind that is already there.');
         }
-        if (g.kind === "orpc") {
-          const gen = new ORPCGenerator(analysis);
-          const { files } = await gen.generate({
-            outputDir: cfg.outDir,
-            template: g.template,
-            includeRelations: g.includeRelations,
-            naming: g.naming,
-            outputHeader: g.outputHeader,
-            format: g.format,
-            templateOptions: g.templateOptions,
-            importExtension: g.importExtension,
-            validation: g.validation,
-            databaseInjection: g.databaseInjection,
-            servicesDir
-          });
-          opts.json ? console.log(JSON.stringify({ event: "generate_complete", kind: g.kind, files })) : console.log(
-            chalk3.green(`Generated (${g.kind}):`),
-            files.map((f) => chalk3.cyan(f)).join(", ")
-          );
+        return;
+      }
+      for (const g of selectGenerators(cfg.generators, selection.kinds)) {
+        const entry = GENERATOR_BY_KIND.get(g.kind);
+        if (!entry) continue;
+        try {
+          const files = await runGenerator(entry, g, cfg, { analysis, servicesDir });
+          watchGenerated(g.kind, files);
           newFiles.push(...files);
-        } else if (g.kind === "trpc") {
-          try {
-            const { TRPCGenerator } = await loadGenerator(
-              "@drzl/generator-trpc",
-              () => import("./dist-XBGVORL3.js")
-            );
-            const gen = new TRPCGenerator(analysis);
-            const { files } = await gen.generate(trpcOptions(g, cfg, servicesDir));
-            opts.json ? console.log(JSON.stringify({ event: "generate_complete", kind: g.kind, files })) : console.log(
-              chalk3.green(`Generated (trpc): ${files.length} files`),
-              files.map((f) => chalk3.cyan(f)).join(", ")
-            );
-            newFiles.push(...files);
-          } catch (e) {
-            reportGeneratorFailure(g.kind, e);
-            return;
-          }
-        } else if (g.kind === "service") {
-          try {
-            const { ServiceGenerator } = await loadGenerator(
-              "@drzl/generator-service",
-              () => import("@drzl/generator-service")
-            );
-            const gen = new ServiceGenerator(analysis);
-            const target = g.path ?? "src/services";
-            const files = await gen.generate({
-              outDir: target,
-              outputHeader: g.outputHeader,
-              format: g.format,
-              dataAccess: g.dataAccess,
-              dbImportPath: g.dbImportPath,
-              schemaImportPath: g.schemaImportPath,
-              importExtension: g.importExtension,
-              databaseInjection: g.databaseInjection
-            });
-            opts.json ? console.log(JSON.stringify({ event: "generate_complete", kind: g.kind, files })) : console.log(
-              chalk3.green(`Generated (service): ${files.length} files`),
-              files.map((f) => chalk3.cyan(f)).join(", ")
-            );
-            newFiles.push(...files);
-          } catch (e) {
-            reportGeneratorFailure(g.kind, e);
-            return;
-          }
-        } else if (g.kind === "zod") {
-          try {
-            const { ZodGenerator } = await loadGenerator(
-              "@drzl/generator-zod",
-              () => import("@drzl/generator-zod")
-            );
-            const gen = new ZodGenerator(analysis);
-            const target = g.path ?? "src/validators/zod";
-            const files = await gen.generate(
-              validationOptions(g, cfg, target, { schemaTypes: true, meta: true })
-            );
-            opts.json ? console.log(JSON.stringify({ event: "generate_complete", kind: g.kind, files })) : console.log(
-              chalk3.green(`Generated (zod): ${files.length} files`),
-              files.map((f) => chalk3.cyan(f)).join(", ")
-            );
-            newFiles.push(...files);
-          } catch (e) {
-            reportGeneratorFailure(g.kind, e);
-            return;
-          }
-        } else if (g.kind === "valibot") {
-          try {
-            const { ValibotGenerator } = await loadGenerator(
-              "@drzl/generator-valibot",
-              () => import("@drzl/generator-valibot")
-            );
-            const gen = new ValibotGenerator(analysis);
-            const target = g.path ?? "src/validators/valibot";
-            const files = await gen.generate(
-              validationOptions(g, cfg, target, { schemaTypes: true })
-            );
-            opts.json ? console.log(JSON.stringify({ event: "generate_complete", kind: g.kind, files })) : console.log(
-              chalk3.green(`Generated (valibot): ${files.length} files`),
-              files.map((f) => chalk3.cyan(f)).join(", ")
-            );
-            newFiles.push(...files);
-          } catch (e) {
-            reportGeneratorFailure(g.kind, e);
-            return;
-          }
-        } else if (g.kind === "arktype") {
-          try {
-            const { ArkTypeGenerator } = await loadGenerator(
-              "@drzl/generator-arktype",
-              () => import("@drzl/generator-arktype")
-            );
-            const gen = new ArkTypeGenerator(analysis);
-            const target = g.path ?? "src/validators/arktype";
-            const files = await gen.generate(
-              validationOptions(g, cfg, target, { schemaTypes: false })
-            );
-            opts.json ? console.log(JSON.stringify({ event: "generate_complete", kind: g.kind, files })) : console.log(
-              chalk3.green(`Generated (arktype): ${files.length} files`),
-              files.map((f) => chalk3.cyan(f)).join(", ")
-            );
-            newFiles.push(...files);
-          } catch (e) {
-            reportGeneratorFailure(g.kind, e);
-            return;
-          }
-        } else if (g.kind === "typebox") {
-          try {
-            const { TypeBoxGenerator } = await loadGenerator(
-              "@drzl/generator-typebox",
-              () => import("@drzl/generator-typebox")
-            );
-            const gen = new TypeBoxGenerator(analysis);
-            const target = g.path ?? "src/validators/typebox";
-            const files = await gen.generate(
-              validationOptions(g, cfg, target, {
-                schemaTypes: true,
-                standardSchema: true
-              })
-            );
-            opts.json ? console.log(JSON.stringify({ event: "generate_complete", kind: g.kind, files })) : console.log(
-              chalk3.green(`Generated (typebox): ${files.length} files`),
-              files.map((f) => chalk3.cyan(f)).join(", ")
-            );
-            newFiles.push(...files);
-          } catch (e) {
-            reportGeneratorFailure(g.kind, e);
-            return;
-          }
-        } else if (g.kind === "effect") {
-          try {
-            const { EffectGenerator } = await loadGenerator(
-              "@drzl/generator-effect",
-              () => import("./dist-WHAW3AMQ.js")
-            );
-            const gen = new EffectGenerator(analysis);
-            const target = g.path ?? "src/validators/effect";
-            const files = await gen.generate(
-              validationOptions(g, cfg, target, { schemaTypes: true })
-            );
-            opts.json ? console.log(JSON.stringify({ event: "generate_complete", kind: g.kind, files })) : console.log(
-              chalk3.green(`Generated (effect): ${files.length} files`),
-              files.map((f) => chalk3.cyan(f)).join(", ")
-            );
-            newFiles.push(...files);
-          } catch (e) {
-            reportGeneratorFailure(g.kind, e);
-            return;
-          }
-        } else if (g.kind === "json-schema") {
-          try {
-            const { JsonSchemaGenerator } = await loadGenerator(
-              "@drzl/generator-json-schema",
-              () => import("./dist-K6N4F3XW.js")
-            );
-            const gen = new JsonSchemaGenerator(analysis);
-            const target = g.path ?? "src/validators/json-schema";
-            const files = await gen.generate(jsonSchemaOptions(g, cfg, target));
-            opts.json ? console.log(JSON.stringify({ event: "generate_complete", kind: g.kind, files })) : console.log(
-              chalk3.green(`Generated (json-schema): ${files.length} files`),
-              files.map((f) => chalk3.cyan(f)).join(", ")
-            );
-            newFiles.push(...files);
-          } catch (e) {
-            reportGeneratorFailure(g.kind, e);
-            return;
-          }
+        } catch (e) {
+          reportGeneratorFailure(out, g.kind, e);
+          return;
         }
       }
       const added = newFiles.filter((f) => !lastFiles.includes(f));
       const removed = lastFiles.filter((f) => !newFiles.includes(f));
-      opts.json ? console.log(JSON.stringify({ event: "diff", added, removed })) : (() => {
-        if (added.length) console.log(chalk3.blue(`Added: ${added.join(", ")}`));
-        if (removed.length) console.log(chalk3.yellow(`Removed: ${removed.join(", ")}`));
-      })();
-      if (newFiles.length && !opts.json) {
-        const reason = opts.pipeline && opts.pipeline !== "all" ? `watch:${opts.pipeline}` : "watch";
-        maybeShowSponsorMessage({ reason });
+      if (opts.json) {
+        out.jsonData({ event: "diff", added, removed });
+      } else {
+        if (added.length) out.note(out.errStyle.blue(`Added: ${added.join(", ")}`));
+        if (removed.length) out.warn(`Removed: ${removed.join(", ")}`);
+      }
+      if (newFiles.length) {
+        const reason = selection.kinds ? `watch:${[...selection.kinds].join(",")}` : "watch";
+        maybeShowSponsorMessage({ reason, out });
       }
       lastFiles = newFiles;
     } catch (e) {
-      opts.json ? console.log(JSON.stringify({ event: "error", message: String(e?.message ?? e) })) : console.error(chalk3.red("Watch pipeline failed:"), e?.message ?? e);
+      const msg = messageOf(e);
+      if (opts.json) out.jsonData({ event: "error", message: msg });
+      else out.error("Watch pipeline failed:", msg);
     }
   };
-  const debounced = Number(opts.debounce) || 200;
-  let timer = null;
+  const scheduler = createRebuildScheduler({
+    run,
+    debounceMs: resolveDebounce(opts.debounce, (w) => out.warn(w))
+  });
   const trigger = (file) => {
     if (file) {
       const full = abs(file);
@@ -1348,62 +3493,73 @@ program.command("watch").description("Watch schema and regenerate on changes").o
         if (full === dir || isInside(full, dir)) return;
       }
     }
-    if (timer) clearTimeout(timer);
-    timer = setTimeout(run, debounced);
+    scheduler.trigger();
   };
   if (opts.json) {
-    console.log(
-      JSON.stringify({
-        event: "watching",
-        targets: Array.from(currentTargets),
-        ignored: Array.from(ignoredOutDirs)
-      })
-    );
+    out.jsonData({
+      event: "watching",
+      targets: Array.from(currentTargets),
+      ignored: Array.from(ignoredOutDirs)
+    });
   } else {
-    console.log(
-      chalk3.gray(
-        "Watching:\n  " + Array.from(currentTargets).map((p) => path4.relative(process.cwd(), p)).join("\n  ")
+    out.note(
+      out.errStyle.gray(
+        "Watching:\n  " + Array.from(currentTargets).map((p) => path7.relative(process.cwd(), p)).join("\n  ")
       )
     );
   }
-  watcher.on("add", (p) => trigger(p)).on("change", (p) => trigger(p)).on("unlink", (p) => trigger(p)).on("error", (err) => console.error(chalk3.red("Watcher error:"), err));
-  await run();
+  watcher.on("add", (p) => trigger(p)).on("change", (p) => trigger(p)).on("unlink", (p) => trigger(p)).on("error", (err) => out.error("Watcher error:", messageOf(err)));
+  await scheduler.runNow();
 });
-program.command("init").description("Scaffold a drzl.config.ts").option("-y, --yes", "accept defaults").action(async (_opts) => {
-  const fs2 = await import("fs/promises");
-  const path5 = await import("path");
-  const target = path5.resolve(process.cwd(), "drzl.config.ts");
-  const template = `export default {
-  schema: 'src/db/schema.ts',
-  outDir: 'src/api',
-  analyzer: { includeRelations: true, validateConstraints: true },
-  generators: [
-    // For tRPC instead: { kind: 'trpc', template: 'standard', includeRelations: true }
-    // To run both, give one of them its own \`path\`; they share \`outDir\` otherwise.
-    { kind: 'orpc', template: 'standard', includeRelations: true }
-  ]
-} as const
-`;
-  try {
-    await fs2.writeFile(target, template, { flag: "wx" });
-    console.log(chalk3.green(`Created ${target}`));
-  } catch (e) {
-    console.error(chalk3.red("Init failed:"), e?.message ?? e);
-    process.exit(1);
+withOutputFlags(
+  program.command("init").description("Scaffold a drzl.config.ts, finding your schema and asking what to generate").option("-y, --yes", "take the defaults and ask nothing").option("--schema <path>", "the schema file to write into the config, skipping detection").option(
+    "--generators <list>",
+    `comma-separated: ${INIT_GENERATOR_CHOICES.map((c) => c.kind).join(", ")}`
+  )
+).action(async (opts) => {
+  const out = outputFor(opts);
+  const failures = [];
+  const outcome = await runInit({
+    cwd: process.cwd(),
+    yes: !!opts.yes || !!opts.json,
+    schemaFlag: opts.schema,
+    generatorsFlag: opts.generators,
+    stdin: process.stdin,
+    stdout: process.stdout,
+    env: process.env,
+    // Narration on stderr, all of it: what `init` produces is a file on disk, and the lines it
+    // prints are a report about that.
+    log: (s) => out.note(s.startsWith("Created ") ? out.errStyle.green(s) : out.errStyle.gray(s)),
+    error: (s) => {
+      failures.push(s);
+      out.error(s);
+    }
+  });
+  if (opts.json) {
+    out.jsonData(
+      outcome.code === 0 ? {
+        ok: true,
+        command: "init",
+        exitCode: EXIT_OK,
+        written: outcome.written,
+        schema: outcome.plan?.schema ?? null,
+        schemaSource: outcome.plan?.schemaSource ?? null,
+        generators: outcome.plan?.generators ?? []
+      } : jsonFailure("init", "DRZL_CLI_INIT", failures.join(" ") || "init did not write a config")
+    );
   }
+  process.exit(outcome.code === 0 ? EXIT_OK : EXIT_FAILED);
 });
-function reportWideColumns(issues) {
+function wideColumnWarning(issues) {
   const wide = issues.filter((i) => i.code === "DRZL_ANL_UNKNOWN_COLUMN");
-  if (!wide.length) return;
-  console.warn(
-    chalk3.yellow(`
-${wide.length} column${wide.length === 1 ? "" : "s"} could not be typed:`)
-  );
-  for (const i of wide.slice(0, 10)) console.warn(chalk3.gray(`  - ${i.message}`));
-  if (wide.length > 10) console.warn(chalk3.gray(`  ... and ${wide.length - 10} more`));
-  const hints = [...new Set(wide.map((i) => i.hint).filter(Boolean))];
-  for (const h of hints) console.warn(chalk3.gray(`  ${h}`));
-  console.warn(chalk3.gray("  Run `drzl doctor` for the full report."));
+  if (!wide.length) return [];
+  const lines = [`
+${wide.length} column${wide.length === 1 ? "" : "s"} could not be typed:`];
+  for (const i of wide.slice(0, 10)) lines.push(`  - ${i.message}`);
+  if (wide.length > 10) lines.push(`  ... and ${wide.length - 10} more`);
+  for (const h of [...new Set(wide.map((i) => i.hint).filter(Boolean))]) lines.push(`  ${h}`);
+  lines.push("  Run `drzl doctor` for the full report.");
+  return [lines.join("\n")];
 }
 program.parseAsync(process.argv);
 //# sourceMappingURL=cli.js.map