@carllee1983/dbcli 1.51.2 → 1.52.0

package/dist/cli.mjs

@@ -52,7 +52,7 @@ var package_default;
 var init_package = __esm(() => {
   package_default = {
     name: "@carllee1983/dbcli",
-    version: "1.51.2",
+    version: "1.52.0",
     description: "Database CLI for AI agents",
     type: "module",
     publishConfig: {
@@ -124,6 +124,7 @@ var init_package = __esm(() => {
       test: "bun test --timeout 30000",
       "test:unit": "bun test tests/unit tests/core",
       "test:integration": "bun test tests/integration",
+      "test:gherkin": "bun test tests/gherkin",
       "test:docker": "docker compose -f docker-compose.test.yml up -d --wait && bun test tests/integration/adapters; docker compose -f docker-compose.test.yml down",
       "docs:check": "bun run scripts/check-user-docs.ts",
       "contract:check": "bun run scripts/check-cli-contract.ts",
@@ -154,6 +155,8 @@ var init_package = __esm(() => {
       zod: "^3.25.76"
     },
     devDependencies: {
+      "@cucumber/gherkin": "^42.0.1",
+      "@cucumber/messages": "^34.2.1",
       "@eslint/js": "^9.39.4",
       "@happy-dom/global-registrator": "^20.10.6",
       "@inquirer/prompts": "^8.4.3",
@@ -80459,6 +80462,9 @@ class QueryResultFormatter {
     if (result.executionTimeMs !== undefined) {
       footerLines.push(`Execution time: ${result.executionTimeMs}ms`);
     }
+    if (result.metadata?.performanceAdvisory) {
+      footerLines.push(`Performance hint: ${result.metadata.performanceAdvisory.recommendation}`);
+    }
     return footerLines.join(" | ");
   }
   formatCSV(result) {
@@ -86348,6 +86354,63 @@ var init_query_fanout = __esm(() => {
   init_permission_guard();
 });
 
+// src/core/slow-query-advisory.ts
+function slowQueryThresholdFor(options) {
+  if (options.recovery === true)
+    return 0;
+  const threshold = options.slowMs ?? DEFAULT_SLOW_QUERY_MS;
+  assertValidSlowQueryThreshold(threshold);
+  return threshold;
+}
+function assertValidSlowQueryThreshold(value) {
+  if (value === undefined)
+    return;
+  if (!Number.isSafeInteger(value) || value < 0) {
+    throw new Error("slow-ms must be a non-negative integer");
+  }
+}
+function parseSlowQueryThreshold(value) {
+  if (!/^\d+$/.test(value)) {
+    throw new Error("slow-ms must be a non-negative integer");
+  }
+  const parsed = Number(value);
+  assertValidSlowQueryThreshold(parsed);
+  return parsed;
+}
+function recommendationFor(system) {
+  const covered = system === undefined || GUIDE_SLOW_QUERY_SYSTEMS.includes(system);
+  return covered ? `Review safely with: dbcli guide slow-query --format markdown. ${NO_EXTRA_WORK}` : `Re-check the query shape and the filters it scans; dbcli ships no slow-query diagnostics for ${system}. ${NO_EXTRA_WORK}`;
+}
+function buildSlowQueryAdvisory(executionTimeMs, options) {
+  const thresholdMs = slowQueryThresholdFor(options);
+  if (thresholdMs === 0 || executionTimeMs === undefined || executionTimeMs < thresholdMs) {
+    return;
+  }
+  return {
+    code: "SLOW_QUERY",
+    executionTimeMs,
+    thresholdMs,
+    recommendation: recommendationFor(options.system)
+  };
+}
+function attachSlowQueryAdvisory(result, options) {
+  const advisory = buildSlowQueryAdvisory(result.executionTimeMs, options);
+  if (!advisory)
+    return result;
+  return {
+    ...result,
+    metadata: {
+      statement: result.metadata?.statement ?? "UNKNOWN",
+      ...result.metadata,
+      performanceAdvisory: advisory
+    }
+  };
+}
+var DEFAULT_SLOW_QUERY_MS = 1000, GUIDE_SLOW_QUERY_SYSTEMS, NO_EXTRA_WORK = "This hint runs no additional database diagnostics.";
+var init_slow_query_advisory = __esm(() => {
+  GUIDE_SLOW_QUERY_SYSTEMS = ["mariadb", "mysql", "postgresql", "redis"];
+});
+
 // src/commands/query-size-guard.ts
 var exports_query_size_guard = {};
 __export(exports_query_size_guard, {
@@ -86409,6 +86472,7 @@ async function queryCommand(sql, options, command) {
     if (options.limit !== undefined && (!Number.isInteger(options.limit) || options.limit <= 0)) {
       throw new Error("--limit must be a positive integer");
     }
+    assertValidSlowQueryThreshold(options.slowMs);
     if (options.format) {
       validateFormat(options.format, [...ALLOWED_FORMATS3, "html"], "query");
     }
@@ -86628,6 +86692,14 @@ async function executeConnectionQuery(query, options, context, fieldSelection) {
     } else {
       execution = await sqlQueryBranch(query, options, context, fieldSelection);
     }
+    execution = {
+      ...execution,
+      result: attachSlowQueryAdvisory(execution.result, {
+        slowMs: options.slowMs,
+        recovery: options.recovery,
+        system
+      })
+    };
     await writeAuditEntry(config, "query", auditOptions, {
       success: true,
       sql: query,
@@ -86936,6 +87008,7 @@ var init_query = __esm(() => {
   init_connection_selector();
   init_query_fanout();
   init_permission_guard();
+  init_slow_query_advisory();
   ALLOWED_FORMATS3 = ["table", "json", "csv"];
 });
 
@@ -87527,14 +87600,14 @@ async function qMongoBranch(snippet, prepared, options, config) {
     } else {
       const columnNames = masked[0] ? Object.keys(masked[0]) : [];
       const formatter = new QueryResultFormatter;
-      console.log(formatter.format({
+      console.log(formatter.format(attachSlowQueryAdvisory({
         rows: masked,
         rowCount: masked.length,
         columnNames,
         columnTypes: [],
         executionTimeMs,
         metadata: { statement: "SELECT", affectedRows: 0 }
-      }, { format: options.format ?? "table" }));
+      }, { slowMs: options.slowMs, recovery: options.recovery, system: "mongodb" }), { format: options.format ?? "table" }));
     }
     await writeAuditEntry(config, "q", options, {
       success: true,
@@ -87555,6 +87628,7 @@ var init_q_mongo = __esm(() => {
   init_html_formatter();
   init_opener();
   init_integration_helper();
+  init_slow_query_advisory();
 });
 
 // src/commands/q.ts
@@ -87591,6 +87665,7 @@ async function qCommand(name2, options, command) {
   let config;
   let targetNameForAudit = name2;
   try {
+    assertValidSlowQueryThreshold(options.slowMs);
     if (!name2?.startsWith("@")) {
       throw new Error(`Snippet name must start with '@' (got '${name2}')`);
     }
@@ -87686,7 +87761,7 @@ async function qCommand(name2, options, command) {
         return;
       }
       const formatter = new QueryResultFormatter;
-      const out = formatter.format({
+      const out = formatter.format(attachSlowQueryAdvisory({
         rows: filtered.filteredRows,
         rowCount: filtered.filteredRows.length,
         columnNames: columnNames.filter((c2) => !filtered.omittedColumns.includes(c2)),
@@ -87698,7 +87773,7 @@ async function qCommand(name2, options, command) {
           ...securityNotification ? { securityNotification } : {}
         },
         ...limitedResult ? { appliedLimit: limitedResult.metadata } : {}
-      }, { format: options.format ?? "table" });
+      }, { slowMs: options.slowMs, recovery: options.recovery, system: connectionSystem }), { format: options.format ?? "table" });
       console.log(out);
       await writeAuditEntry(config, "q", options, {
         success: true,
@@ -87915,6 +87990,7 @@ var init_q = __esm(() => {
   init_applied_limit();
   init_cli_error();
   init_strategies();
+  init_slow_query_advisory();
 });
 
 // src/core/saved-queries/fold.ts
@@ -93917,7 +93993,7 @@ var init_normalized_schema = __esm(() => {
     }))
   });
   normalizedSchemaZod = exports_external.object({
-    source: exports_external.enum(["db", "prisma", "ddl", "json", "drizzle", "typeorm", "sequelize"]),
+    source: exports_external.enum(["db", "design", "prisma", "ddl", "json", "drizzle", "typeorm", "sequelize"]),
     defaultSchema: exports_external.string().min(1).optional(),
     tables: exports_external.array(tableZod),
     unparsed: exports_external.array(exports_external.object({ location: exports_external.string(), reason: exports_external.string().startsWith("blocked:") }))
@@ -94059,6 +94135,7 @@ function compareNormalized(orm, db, opts) {
   const extraDefaultIgnore = opts.extraDefaultIgnore ?? [];
   const defaultIgnore = [...DEFAULT_IGNORE, ...extraDefaultIgnore];
   const ignorePatterns = opts.ignore.map(globToRegex2);
+  const targetLabel = opts.targetLabel ?? "database";
   const entries = [];
   for (const tableKey of tableKeys) {
     const ormTable = ormTables.get(tableKey);
@@ -94084,7 +94161,7 @@ function compareNormalized(orm, db, opts) {
         severity: "error",
         table,
         object: "table",
-        detail: `table '${table}' is defined in ${orm.source} but absent in the database`
+        detail: `table '${table}' is defined in ${orm.source} but absent in the ${targetLabel}`
       }));
       continue;
     }
@@ -94094,12 +94171,12 @@ function compareNormalized(orm, db, opts) {
         severity: "warn",
         table,
         object: "table",
-        detail: `table '${table}' exists in the database but is not defined in ${orm.source}`
+        detail: `table '${table}' exists in the ${targetLabel} but is not defined in ${orm.source}`
       }));
       continue;
     }
     if (ormTable && dbTable)
-      compareTable(ormTable, dbTable, table, orm.source, entries);
+      compareTable(ormTable, dbTable, table, orm.source, targetLabel, entries);
   }
   entries.sort(entryOrder);
   const summary = {
@@ -94115,7 +94192,7 @@ function compareNormalized(orm, db, opts) {
     summary
   };
 }
-function compareTable(ormTable, dbTable, table, ormSource, entries) {
+function compareTable(ormTable, dbTable, table, ormSource, targetLabel, entries) {
   const ormColumns = new Map(ormTable.columns.map((column) => [column.name.toLowerCase(), column]));
   const dbColumns = new Map(dbTable.columns.map((column) => [column.name.toLowerCase(), column]));
   for (const [columnKey, ormColumn] of ormColumns) {
@@ -94126,7 +94203,7 @@ function compareTable(ormTable, dbTable, table, ormSource, entries) {
         severity: "error",
         table,
         object: ormColumn.name,
-        detail: `column '${ormColumn.name}' (${ormColumn.type}) is defined in ${ormSource} but absent in the database`
+        detail: `column '${ormColumn.name}' (${ormColumn.type}) is defined in ${ormSource} but absent in the ${targetLabel}`
       }, { kind: "column", table: ormTable.identity, column: ormColumn }));
       continue;
     }
@@ -94149,10 +94226,44 @@ function compareTable(ormTable, dbTable, table, ormSource, entries) {
       severity: "warn",
       table,
       object: dbColumn.name,
-      detail: `column '${dbColumn.name}' (${dbColumn.type}) exists in the database but is not defined in ${ormSource}`
+      detail: `column '${dbColumn.name}' (${dbColumn.type}) exists in the ${targetLabel} but is not defined in ${ormSource}`
     }));
   }
-  compareIndexes(ormTable.indexes, dbTable.indexes, ormTable.identity, table, ormSource, entries);
+  compareIndexes(ormTable.indexes, dbTable.indexes, ormTable.identity, table, ormSource, targetLabel, entries);
+  compareForeignKeys(ormTable.foreignKeys, dbTable.foreignKeys, table, ormSource, targetLabel, entries);
+}
+function compareForeignKeys(ormForeignKeys, dbForeignKeys, table, ormSource, targetLabel, entries) {
+  const ormByKey = new Map(ormForeignKeys.map((foreignKey) => [foreignKeyKey(foreignKey), foreignKey]));
+  const dbByKey = new Map(dbForeignKeys.map((foreignKey) => [foreignKeyKey(foreignKey), foreignKey]));
+  for (const [key, foreignKey] of ormByKey) {
+    if (dbByKey.has(key))
+      continue;
+    entries.push(entryWithProposals({
+      category: "missing_in_db",
+      severity: "error",
+      table,
+      object: `foreign key (${foreignKey.columns.join(", ")})`,
+      detail: `foreign key (${foreignKey.columns.join(", ")}) \u2192 ${qualifiedTableName(foreignKey.refTable)}(${foreignKey.refColumns.join(", ")}) is defined in ${ormSource} but absent in the ${targetLabel}`
+    }));
+  }
+  for (const [key, foreignKey] of dbByKey) {
+    if (ormByKey.has(key))
+      continue;
+    entries.push(entryWithProposals({
+      category: "missing_in_orm",
+      severity: "warn",
+      table,
+      object: `foreign key (${foreignKey.columns.join(", ")})`,
+      detail: `foreign key (${foreignKey.columns.join(", ")}) \u2192 ${qualifiedTableName(foreignKey.refTable)}(${foreignKey.refColumns.join(", ")}) exists in the ${targetLabel} but is not defined in ${ormSource}`
+    }));
+  }
+}
+function foreignKeyKey(foreignKey) {
+  return [
+    foreignKey.columns.join("\x00"),
+    tableIdentityKey(foreignKey.refTable),
+    foreignKey.refColumns.join("\x00")
+  ].join("\x01");
 }
 function columnMismatch(ormColumn, dbColumn) {
   const reasons = [];
@@ -94180,7 +94291,7 @@ function columnMismatch(ormColumn, dbColumn) {
 function displayOptional(value) {
   return value === undefined ? "none" : value;
 }
-function compareIndexes(ormIndexes, dbIndexes, tableIdentity, table, ormSource, entries) {
+function compareIndexes(ormIndexes, dbIndexes, tableIdentity, table, ormSource, targetLabel, entries) {
   const indexKey = (index) => JSON.stringify([index.columns.map((column) => column.toLowerCase()), index.unique]);
   const dbKeys = new Set(dbIndexes.map(indexKey));
   const ormKeys = new Set(ormIndexes.map(indexKey));
@@ -94196,7 +94307,7 @@ function compareIndexes(ormIndexes, dbIndexes, tableIdentity, table, ormSource,
       severity: "error",
       table,
       object: `index(${index.columns.join(",")})`,
-      detail: `${index.unique ? "unique " : ""}index on (${index.columns.join(", ")}) is defined in ${ormSource} but absent in the database`
+      detail: `${index.unique ? "unique " : ""}index on (${index.columns.join(", ")}) is defined in ${ormSource} but absent in the ${targetLabel}`
     }, { kind: "index", table: tableIdentity, index }));
   }
   for (const index of dbIndexes) {
@@ -94209,7 +94320,7 @@ function compareIndexes(ormIndexes, dbIndexes, tableIdentity, table, ormSource,
       severity: "warn",
       table,
       object: `index(${index.columns.join(",")})`,
-      detail: `${index.unique ? "unique " : ""}index on (${index.columns.join(", ")}) exists in the database but is not defined in ${ormSource}`
+      detail: `${index.unique ? "unique " : ""}index on (${index.columns.join(", ")}) exists in the ${targetLabel} but is not defined in ${ormSource}`
     }, { kind: "index", table: tableIdentity, index }));
   }
 }
@@ -94417,15 +94528,7 @@ function mergeNormalizedSchemas(schemas) {
     unparsed: schemas.flatMap((schema) => schema.unparsed)
   });
 }
-async function runDrift(paths, options, config) {
-  const system = config.connection?.system;
-  if (!system || !["postgresql", "mysql", "mariadb"].includes(system)) {
-    throw new Error(`This command requires a SQL connection, got: ${system ?? "none"}`);
-  }
-  const cached2 = config.schema ?? {};
-  if (Object.keys(cached2).length === 0) {
-    throw new Error("Schema cache is empty. Run 'dbcli schema' first.");
-  }
+async function loadOrmSchema(paths, options) {
   const ormFormat = parseOrmFormat(options.ormFormat);
   const includesGlob = parseAgainstOrmValues(paths).some(hasGlobMagic);
   const expandedPaths = await expandOrmPaths(paths);
@@ -94456,25 +94559,41 @@ async function runDrift(paths, options, config) {
   if (includesGlob && inputs.some((input) => !isDdlFormat(input.format))) {
     throw new Error("Glob ORM schema inputs are supported only for DDL");
   }
-  const merged = inputs.every((input) => isDdlFormat(input.format)) ? parseDdlFiles(inputs.map((input) => input.content), system) : mergeNormalizedSchemas(inputs.map(({ content, format }) => {
+  const merged = inputs.every((input) => isDdlFormat(input.format)) ? parseDdlFiles(inputs.map((input) => input.content), options.system) : mergeNormalizedSchemas(inputs.map(({ content, format }) => {
     if (format === "prisma")
       return parsePrismaSchema(content);
-    if (format === "ddl" || format in ORM_ALIASES) {
-      return parseDdl(content, system);
-    }
+    if (format === "ddl" || format in ORM_ALIASES)
+      return parseDdl(content, options.system);
     if (format === "drizzle")
       return parseDrizzleSnapshot(JSON.parse(content));
     const parsed = normalizedSchemaZod.parse(JSON.parse(content));
     return { ...parsed, source: "json" };
   }));
   const alias = ormFormat && ormFormat in ORM_ALIASES ? ormFormat : undefined;
-  const orm = alias ? { ...merged, source: alias } : merged;
+  return {
+    schema: alias ? { ...merged, source: alias } : merged,
+    ...alias ? { extraDefaultIgnore: [...ORM_ALIASES[alias].defaultIgnore] } : {}
+  };
+}
+async function runDrift(paths, options, config) {
+  const system = config.connection?.system;
+  if (!system || !["postgresql", "mysql", "mariadb"].includes(system)) {
+    throw new Error(`This command requires a SQL connection, got: ${system ?? "none"}`);
+  }
+  const cached2 = config.schema ?? {};
+  if (Object.keys(cached2).length === 0) {
+    throw new Error("Schema cache is empty. Run 'dbcli schema' first.");
+  }
+  const { schema: orm, extraDefaultIgnore } = await loadOrmSchema(paths, {
+    ...options.ormFormat !== undefined && { ormFormat: options.ormFormat },
+    system
+  });
   const ignore = (options.ignore ?? "").split(",").map((pattern) => pattern.trim()).filter(Boolean);
   const db = normalizeDbSchema(cached2, system === "postgresql" ? { defaultSchema: "public" } : undefined);
   return {
     report: compareNormalized(orm, db, {
       ignore,
-      extraDefaultIgnore: alias ? [...ORM_ALIASES[alias].defaultIgnore] : undefined
+      extraDefaultIgnore
     })
   };
 }
@@ -108079,6 +108198,632 @@ var init_semantic2 = __esm(() => {
   });
 });
 
+// src/core/design/index.ts
+import { join as join40 } from "path";
+function defaultDesignFile(workspaceRoot) {
+  return join40(workspaceRoot, DEFAULT_FILE2);
+}
+function parseDesignSpec(raw, filePath = DEFAULT_FILE2) {
+  const parsed = specSchema.safeParse(raw);
+  if (!parsed.success) {
+    throw new DesignValidationError(filePath, parsed.error.issues.map((issue2) => ({
+      path: formatZodPath(issue2.path),
+      message: issue2.message
+    })));
+  }
+  return normalizeSpec(parsed.data);
+}
+async function loadDesignSpec(filePath) {
+  const file = Bun.file(filePath);
+  if (!await file.exists()) {
+    throw new DesignValidationError(filePath, [{ path: "$", message: "file not found" }]);
+  }
+  if (file.size > MAX_FILE_BYTES2) {
+    throw new DesignValidationError(filePath, [
+      { path: "$", message: `must not exceed ${MAX_FILE_BYTES2} bytes` }
+    ]);
+  }
+  try {
+    return parseDesignSpec(JSON.parse(await file.text()), filePath);
+  } catch (error) {
+    if (error instanceof DesignValidationError)
+      throw error;
+    throw new DesignValidationError(filePath, [{ path: "$", message: "must be valid JSON" }]);
+  }
+}
+function reviewDesign(spec) {
+  const findings = [];
+  const models = new Map;
+  const tables = new Map;
+  if (spec.models.length === 0)
+    addFinding(findings, "error", "NO_MODELS", "$.models", "must contain at least one model");
+  for (const [modelIndex, model] of spec.models.entries()) {
+    const path6 = `$.models[${modelIndex}]`;
+    if (models.has(model.name))
+      addFinding(findings, "error", "DUPLICATE_MODEL", `${path6}.name`, "must be unique");
+    else
+      models.set(model.name, { model, index: modelIndex });
+    if (tables.has(model.table))
+      addFinding(findings, "error", "DUPLICATE_TABLE", `${path6}.table`, "must be unique");
+    else
+      tables.set(model.table, modelIndex);
+    reviewModel(model, modelIndex, findings);
+  }
+  const relationships = new Set;
+  for (const [relationshipIndex, relationship] of spec.relationships.entries()) {
+    const path6 = `$.relationships[${relationshipIndex}]`;
+    const key = `${relationship.from.model}\x00${relationship.from.field}\x00${relationship.to.model}\x00${relationship.to.field}`;
+    const reverseKey = `${relationship.to.model}\x00${relationship.to.field}\x00${relationship.from.model}\x00${relationship.from.field}`;
+    if (relationships.has(key))
+      addFinding(findings, "error", "DUPLICATE_RELATIONSHIP", path6, "must not repeat relationship endpoints");
+    else if (key !== reverseKey && relationships.has(reverseKey)) {
+      addFinding(findings, "error", "REVERSE_RELATIONSHIP", path6, "must use one relationship direction; the reverse endpoints are already declared");
+    }
+    relationships.add(key);
+    reviewRelationship(relationship, path6, models, findings);
+  }
+  for (const [patternIndex, pattern] of spec.accessPatterns.entries()) {
+    reviewAccessPattern(pattern, `$.accessPatterns[${patternIndex}]`, models, findings);
+  }
+  findings.sort(findingOrder);
+  return {
+    findings,
+    summary: {
+      errors: findings.filter((finding) => finding.severity === "error").length,
+      warns: findings.filter((finding) => finding.severity === "warn").length,
+      infos: findings.filter((finding) => finding.severity === "info").length
+    }
+  };
+}
+function compileDesignSchema(spec) {
+  const models = new Map(spec.models.map((model) => [model.name, model]));
+  return {
+    source: "design",
+    ...spec.dialect === "postgresql" ? { defaultSchema: "public" } : {},
+    tables: spec.models.map((model) => ({
+      identity: { table: model.table },
+      columns: model.fields.map((field) => ({
+        name: field.name,
+        type: field.type,
+        nullable: field.nullable,
+        primaryKey: field.primaryKey || undefined
+      })),
+      indexes: [
+        ...model.indexes.map((index) => ({ ...index })),
+        ...model.fields.filter((field) => field.unique && !field.primaryKey).map((field) => ({ columns: [field.name], unique: true }))
+      ],
+      foreignKeys: spec.relationships.flatMap((relationship) => {
+        if (relationship.cardinality === "many-to-many" || relationship.from.model !== model.name)
+          return [];
+        const target = models.get(relationship.to.model);
+        if (!target)
+          return [];
+        return [
+          {
+            columns: [relationship.from.field],
+            refTable: { table: target.table },
+            refColumns: [relationship.to.field]
+          }
+        ];
+      })
+    })),
+    unparsed: []
+  };
+}
+function planDesignProposals(report) {
+  return {
+    report,
+    proposals: report.entries.filter((entry) => entry.category !== "unmanaged").map((entry) => ({
+      table: entry.table,
+      object: entry.object,
+      safety: entry.proposedCommands.some((command) => command.startsWith("# dry-run")) ? "dry-run" : "migration-review",
+      commands: entry.proposedCommands,
+      preflight: [
+        "dbcli blacklist list",
+        "Confirm the exact affected table with: dbcli schema <exact-table> --format json"
+      ],
+      rollback: "Capture the current schema and generated DDL before any approved write; define the inverse migration before execution.",
+      verification: [
+        "After an approved write, run: dbcli schema <exact-table> --format json",
+        "Re-run this same design diff command and review the remaining drift."
+      ]
+    }))
+  };
+}
+function reviewModel(model, modelIndex, findings) {
+  const fields = new Map;
+  const primaryKeys = model.fields.filter((field) => field.primaryKey);
+  if (primaryKeys.length !== 1)
+    addFinding(findings, "error", "PRIMARY_KEY_COUNT", `$.models[${modelIndex}].fields`, "must declare exactly one primary-key field in v1");
+  for (const [fieldIndex, field] of model.fields.entries()) {
+    const path6 = `$.models[${modelIndex}].fields[${fieldIndex}]`;
+    if (fields.has(field.name))
+      addFinding(findings, "error", "DUPLICATE_FIELD", `${path6}.name`, "must be unique within its model");
+    else
+      fields.set(field.name, fieldIndex);
+    if (field.primaryKey && field.nullable)
+      addFinding(findings, "error", "NULLABLE_PRIMARY_KEY", `${path6}.nullable`, "primary-key fields must not be nullable");
+  }
+  const indexKeys = new Set;
+  for (const [indexIndex, index] of model.indexes.entries()) {
+    const path6 = `$.models[${modelIndex}].indexes[${indexIndex}]`;
+    const key = `${index.unique}\x00${index.columns.join("\x00")}`;
+    if (indexKeys.has(key))
+      addFinding(findings, "warn", "DUPLICATE_INDEX", path6, "duplicates a prior index");
+    indexKeys.add(key);
+    for (const column of index.columns) {
+      if (!fields.has(column))
+        addFinding(findings, "error", "UNKNOWN_INDEX_FIELD", `${path6}.columns`, `references unknown field '${column}'`);
+    }
+    if (index.columns.length === 1 && primaryKeys.some((field) => field.name === index.columns[0])) {
+      addFinding(findings, "warn", "REDUNDANT_PRIMARY_KEY_INDEX", path6, "primary-key fields are already indexed");
+    }
+    if (!index.unique && model.indexes.some((candidate) => candidate.columns.length > index.columns.length && index.columns.every((column, columnIndex) => candidate.columns[columnIndex] === column))) {
+      addFinding(findings, "warn", "PREFIX_REDUNDANT_INDEX", path6, "is covered by a longer index with the same leading columns");
+    }
+  }
+}
+function reviewRelationship(relationship, path6, models, findings) {
+  const from = lookupField(relationship.from, `${path6}.from`, models, findings);
+  const to = lookupField(relationship.to, `${path6}.to`, models, findings);
+  if (!from || !to)
+    return;
+  if (relationship.cardinality === "many-to-many") {
+    addFinding(findings, "error", "MANY_TO_MANY_REQUIRES_BRIDGE", `${path6}.cardinality`, "requires an explicit bridge model in v1");
+  }
+  if (typeFamily(from.field.type) !== typeFamily(to.field.type)) {
+    addFinding(findings, "error", "RELATIONSHIP_TYPE_MISMATCH", path6, `field types are incompatible (${from.field.type} vs ${to.field.type})`);
+  }
+  if (relationship.cardinality === "one-to-one" && !isUniqueField(from.model, from.field.name)) {
+    addFinding(findings, "error", "ONE_TO_ONE_REQUIRES_UNIQUE_FK", `${path6}.from.field`, "must be primary-key, unique, or covered by a single-column unique index");
+  }
+}
+function reviewAccessPattern(pattern, path6, models, findings) {
+  const found = models.get(pattern.model);
+  if (!found) {
+    addFinding(findings, "error", "UNKNOWN_ACCESS_MODEL", `${path6}.model`, `references unknown model '${pattern.model}'`);
+    return;
+  }
+  const fields = new Set(found.model.fields.map((field) => field.name));
+  for (const field of [...pattern.filters, ...pattern.sort]) {
+    if (!fields.has(field))
+      addFinding(findings, "error", "UNKNOWN_ACCESS_FIELD", path6, `references unknown field '${field}'`);
+  }
+  const needed = [...pattern.filters, ...pattern.sort];
+  if (needed.length > 0 && !hasSupportingIndex(found.model, needed)) {
+    addFinding(findings, "warn", "ACCESS_PATTERN_INDEX", path6, `consider an index beginning with (${needed.join(", ")})`);
+  }
+}
+function lookupField(endpoint, path6, models, findings) {
+  const found = models.get(endpoint.model);
+  if (!found) {
+    addFinding(findings, "error", "UNKNOWN_RELATIONSHIP_MODEL", `${path6}.model`, `references unknown model '${endpoint.model}'`);
+    return;
+  }
+  const field = found.model.fields.find((candidate) => candidate.name === endpoint.field);
+  if (!field) {
+    addFinding(findings, "error", "UNKNOWN_RELATIONSHIP_FIELD", `${path6}.field`, `references unknown field '${endpoint.field}'`);
+    return;
+  }
+  return { model: found.model, field };
+}
+function isUniqueField(model, field) {
+  return model.fields.some((candidate) => candidate.name === field && (candidate.primaryKey || candidate.unique)) || model.indexes.some((index) => index.unique && index.columns.length === 1 && index.columns[0] === field);
+}
+function hasSupportingIndex(model, needed) {
+  const indexes = [
+    ...model.indexes.map((index) => index.columns),
+    ...model.fields.filter((field) => field.primaryKey || field.unique).map((field) => [field.name])
+  ];
+  return indexes.some((columns) => needed.every((column, index) => columns[index] === column));
+}
+function addFinding(findings, severity, code, path6, message) {
+  findings.push({ severity, code, path: path6, message });
+}
+function normalizeSpec(spec) {
+  return {
+    ...spec,
+    models: [...spec.models].sort((left, right) => codePointOrder2(left.name, right.name)),
+    relationships: [...spec.relationships].sort((left, right) => codePointOrder2(left.name, right.name)),
+    accessPatterns: [...spec.accessPatterns].sort((left, right) => {
+      const leftKey = `${left.model}\x00${left.filters.join("\x00")}\x00${left.sort.join("\x00")}`;
+      const rightKey = `${right.model}\x00${right.filters.join("\x00")}\x00${right.sort.join("\x00")}`;
+      return codePointOrder2(leftKey, rightKey);
+    }),
+    decisions: [...spec.decisions].sort((left, right) => codePointOrder2(left.name, right.name))
+  };
+}
+function formatZodPath(path6) {
+  return path6.reduce((result, part) => typeof part === "number" ? `${result}[${part}]` : `${result}.${part}`, "$");
+}
+function findingOrder(left, right) {
+  return codePointOrder2(left.path, right.path) || codePointOrder2(left.code, right.code) || codePointOrder2(left.message, right.message);
+}
+function codePointOrder2(left, right) {
+  const leftPoints = [...left];
+  const rightPoints = [...right];
+  for (let index = 0;index < Math.min(leftPoints.length, rightPoints.length); index += 1) {
+    const difference = leftPoints[index].codePointAt(0) - rightPoints[index].codePointAt(0);
+    if (difference !== 0)
+      return difference;
+  }
+  return leftPoints.length - rightPoints.length;
+}
+var DesignValidationError, DEFAULT_FILE2 = "dbcli.design.json", MAX_FILE_BYTES2, MAX_MODELS2 = 100, MAX_FIELDS_PER_MODEL2 = 100, MAX_RELATIONSHIPS2 = 200, MAX_ACCESS_PATTERNS = 200, IDENTIFIER3, DESIGN_NAME, TYPE, UNSAFE_TEXT, identifier, designName, text2, fieldSchema, indexSchema, modelSchema, endpointSchema, relationshipSchema, accessPatternSchema, decisionSchema, specSchema;
+var init_design = __esm(() => {
+  init_zod();
+  init_normalized_schema();
+  DesignValidationError = class DesignValidationError extends Error {
+    filePath;
+    issues;
+    constructor(filePath, issues) {
+      super(`Invalid design artifact at ${filePath}: ${issues.map((issue2) => `${issue2.path}: ${issue2.message}`).join("; ")}`);
+      this.filePath = filePath;
+      this.issues = issues;
+      this.name = "DesignValidationError";
+    }
+  };
+  MAX_FILE_BYTES2 = 256 * 1024;
+  IDENTIFIER3 = /^[A-Za-z_][A-Za-z0-9_]*$/;
+  DESIGN_NAME = /^[a-z][a-z0-9-]*$/;
+  TYPE = /^[^;\r\n]{1,100}$/;
+  UNSAFE_TEXT = /(?:\b(?:select|insert|update|delete|alter|drop|grant)\b\s+|\bcreate\s+(?:table|index)\b|(?:postgres(?:ql)?|mysql):\/\/)/i;
+  identifier = exports_external.string().regex(IDENTIFIER3, "must be a SQL-safe identifier");
+  designName = exports_external.string().regex(DESIGN_NAME, "must be lowercase kebab-case");
+  text2 = exports_external.string().min(1).max(1000).refine((value) => !UNSAFE_TEXT.test(value), "must not contain SQL or connection data");
+  fieldSchema = exports_external.object({
+    name: identifier,
+    type: exports_external.string().regex(TYPE, "must be a bounded type declaration without SQL separators").refine((value) => !UNSAFE_TEXT.test(value), "must not contain SQL or connection data"),
+    nullable: exports_external.boolean(),
+    primaryKey: exports_external.boolean().optional().default(false),
+    unique: exports_external.boolean().optional().default(false),
+    description: text2.optional()
+  }).strict();
+  indexSchema = exports_external.object({
+    name: identifier.optional(),
+    columns: exports_external.array(identifier).min(1).max(16),
+    unique: exports_external.boolean().optional().default(false)
+  }).strict();
+  modelSchema = exports_external.object({
+    name: designName,
+    table: identifier,
+    description: text2.optional(),
+    fields: exports_external.array(fieldSchema).max(MAX_FIELDS_PER_MODEL2),
+    indexes: exports_external.array(indexSchema).optional().default([])
+  }).strict();
+  endpointSchema = exports_external.object({ model: designName, field: identifier }).strict();
+  relationshipSchema = exports_external.object({
+    name: designName,
+    from: endpointSchema,
+    to: endpointSchema,
+    cardinality: exports_external.enum(["one-to-one", "one-to-many", "many-to-one", "many-to-many"]),
+    description: text2.optional()
+  }).strict();
+  accessPatternSchema = exports_external.object({
+    model: designName,
+    filters: exports_external.array(identifier).max(16).optional().default([]),
+    sort: exports_external.array(identifier).max(16).optional().default([]),
+    description: text2.optional()
+  }).strict();
+  decisionSchema = exports_external.object({ name: designName, rationale: text2 }).strict();
+  specSchema = exports_external.object({
+    version: exports_external.literal(1),
+    dialect: exports_external.enum(["postgresql", "mysql", "mariadb"]),
+    models: exports_external.array(modelSchema).max(MAX_MODELS2),
+    relationships: exports_external.array(relationshipSchema).max(MAX_RELATIONSHIPS2).optional().default([]),
+    accessPatterns: exports_external.array(accessPatternSchema).max(MAX_ACCESS_PATTERNS).optional().default([]),
+    decisions: exports_external.array(decisionSchema).max(100).optional().default([])
+  }).strict();
+});
+
+// src/formatters/design.ts
+function formatDesign(spec, review, format) {
+  if (format === "json")
+    return JSON.stringify({ spec, review }, null, 2);
+  if (format === "mermaid")
+    return formatMermaid(spec);
+  return formatMarkdown2(spec, review);
+}
+function formatDesignReview(review, format) {
+  if (format === "json")
+    return JSON.stringify(review, null, 2);
+  const lines = ["# Design review", ""];
+  if (review.findings.length === 0)
+    lines.push("No design findings.");
+  else {
+    lines.push("| Severity | Code | Location | Finding |", "| --- | --- | --- | --- |");
+    for (const finding of review.findings) {
+      lines.push(`| ${finding.severity} | ${finding.code} | ${escapeTable(finding.path)} | ${escapeTable(finding.message)} |`);
+    }
+  }
+  lines.push("", `Summary: ${review.summary.errors} error(s), ${review.summary.warns} warning(s), ${review.summary.infos} info(s).`);
+  return lines.join(`
+`);
+}
+function formatDesignProposal(plan, format) {
+  if (format === "json")
+    return JSON.stringify(plan, null, 2);
+  const lines = ["# Design change proposal", ""];
+  if (plan.proposals.length === 0)
+    lines.push("No design changes need a proposal.");
+  for (const proposal of plan.proposals) {
+    lines.push(`## ${proposal.table}.${proposal.object}`, "", `Safety: **${proposal.safety}**`, "", "Preflight:");
+    for (const step of proposal.preflight)
+      lines.push(`- ${inlineCode2(step)}`);
+    lines.push("", "Proposed command or escalation:");
+    lines.push("```bash", ...proposal.commands, "```", "", `Rollback: ${proposal.rollback}`, "", "Verification:");
+    for (const step of proposal.verification)
+      lines.push(`- ${inlineCode2(step)}`);
+    lines.push("");
+  }
+  lines.push(`Drift summary: ${plan.report.summary.errors} error(s), ${plan.report.summary.warns} warning(s).`);
+  return lines.join(`
+`);
+}
+function formatMarkdown2(spec, review) {
+  const lines = ["# Database Design", "", `Dialect: \`${spec.dialect}\``, ""];
+  for (const model of spec.models) {
+    lines.push(`## ${model.name}`, "", `Physical table: \`${model.table}\``);
+    if (model.description)
+      lines.push("", escapeText(model.description));
+    lines.push("", "| Field | Type | Nullable | Key |", "| --- | --- | --- | --- |");
+    for (const field of model.fields) {
+      const key = field.primaryKey ? "primary" : field.unique ? "unique" : "";
+      lines.push(`| \`${field.name}\` | \`${field.type}\` | ${field.nullable ? "yes" : "no"} | ${key} |`);
+    }
+    if (model.indexes.length > 0) {
+      lines.push("", "Indexes:");
+      for (const index of model.indexes) {
+        lines.push(`- ${index.unique ? "unique " : ""}index on \`${index.columns.join(", ")}\``);
+      }
+    }
+    lines.push("");
+  }
+  if (spec.relationships.length > 0) {
+    lines.push("## Relationships", "");
+    for (const relationship of spec.relationships) {
+      lines.push(`- \`${relationship.name}\`: \`${relationship.from.model}.${relationship.from.field}\` \u2192 \`${relationship.to.model}.${relationship.to.field}\` (${relationship.cardinality})`);
+    }
+    lines.push("");
+  }
+  if (spec.accessPatterns.length > 0) {
+    lines.push("## Access patterns", "");
+    for (const pattern of spec.accessPatterns) {
+      lines.push(`- \`${pattern.model}\`: filter ${inlineList(pattern.filters)}; sort ${inlineList(pattern.sort)}`);
+    }
+    lines.push("");
+  }
+  if (spec.decisions.length > 0) {
+    lines.push("## Decisions", "");
+    for (const decision of spec.decisions)
+      lines.push(`- **${decision.name}** \u2014 ${escapeText(decision.rationale)}`);
+    lines.push("");
+  }
+  lines.push(formatDesignReview(review, "markdown"));
+  return lines.join(`
+`);
+}
+function formatMermaid(spec) {
+  const lines = ["erDiagram"];
+  for (const model of spec.models) {
+    lines.push(`  ${model.table} {`);
+    for (const field of model.fields) {
+      const markers = [field.primaryKey ? "PK" : "", field.unique && !field.primaryKey ? "UK" : ""].filter(Boolean).join(", ");
+      lines.push(`    ${mermaidType(field.type)} ${field.name}${markers ? ` "${markers}"` : ""}`);
+    }
+    lines.push("  }");
+  }
+  const models = new Map(spec.models.map((model) => [model.name, model]));
+  for (const relationship of spec.relationships) {
+    const from = models.get(relationship.from.model);
+    const to = models.get(relationship.to.model);
+    if (!from || !to)
+      continue;
+    lines.push(`  ${from.table} ${mermaidCardinality(relationship.cardinality)} ${to.table} : "${relationship.name}"`);
+  }
+  return lines.join(`
+`);
+}
+function mermaidCardinality(cardinality) {
+  if (cardinality === "one-to-one")
+    return "||--||";
+  if (cardinality === "one-to-many")
+    return "||--o{";
+  if (cardinality === "many-to-one")
+    return "}o--||";
+  return "}o--o{";
+}
+function mermaidType(type) {
+  return type.replace(/[^A-Za-z0-9_]/g, "_");
+}
+function inlineList(values) {
+  return values.length === 0 ? "none" : values.map((value) => `\`${value}\``).join(", ");
+}
+function inlineCode2(value) {
+  return `\`${value.replace(/`/g, "\\`")}\``;
+}
+function escapeTable(value) {
+  return value.replace(/\\/g, "\\\\").replace(/\|/g, "\\|").replace(/\r\n|\r|\n/g, "<br>");
+}
+function escapeText(value) {
+  return value.replace(/([`*_{}[\]()#+.!|>~-])/g, "\\$1").replace(/\r\n|\r|\n/g, "<br>");
+}
+
+// src/commands/design.ts
+function defaultFile(file) {
+  return file ?? defaultDesignFile(process.cwd());
+}
+function collectOption2(value, previous) {
+  return [...previous, value];
+}
+function parseIgnore(value) {
+  return (value ?? "").split(",").map((pattern) => pattern.trim()).filter(Boolean);
+}
+function template(dialect) {
+  return JSON.stringify({
+    version: 1,
+    dialect,
+    models: [],
+    relationships: [],
+    accessPatterns: [],
+    decisions: []
+  }, null, 2) + `
+`;
+}
+function fail2(error, format) {
+  if (error instanceof DesignValidationError) {
+    const report = {
+      findings: error.issues.map((issue2) => ({
+        ...issue2,
+        code: "INVALID_ARTIFACT",
+        severity: "error"
+      })),
+      summary: { errors: error.issues.length, warns: 0, infos: 0 }
+    };
+    console.log(formatDesignReview(report, format));
+  } else {
+    console.error(error.message);
+  }
+  process.exit(1);
+}
+async function compareAgainstCache(desired, dialect, ignore, command) {
+  const config = await configModule.read(resolveConfigPath(command));
+  const system = config.connection?.system;
+  if (!system || !["postgresql", "mysql", "mariadb"].includes(system)) {
+    throw new Error("design comparison against cache requires a configured PostgreSQL, MySQL, or MariaDB connection");
+  }
+  if (system !== dialect) {
+    throw new Error(`design dialect '${dialect}' does not match configured connection '${system}'`);
+  }
+  if (Object.keys(config.schema ?? {}).length === 0) {
+    throw new Error("Schema cache is empty. Run 'dbcli schema' first.");
+  }
+  const actual = normalizeDbSchema(config.schema, system === "postgresql" ? { defaultSchema: "public" } : {});
+  return compareNormalized(desired, actual, { ignore });
+}
+async function compareAgainstOrm(desired, dialect, paths, ormFormat, ignore) {
+  const { schema: orm, extraDefaultIgnore } = await loadOrmSchema(parseAgainstOrmValues(paths), {
+    ...ormFormat !== undefined && { ormFormat },
+    system: dialect
+  });
+  return compareNormalized(desired, orm, {
+    ignore,
+    extraDefaultIgnore,
+    targetLabel: "ORM definition"
+  });
+}
+function isFormat(value, formats) {
+  return value !== undefined && formats.includes(value);
+}
+var VALIDATE_FORMATS, RENDER_FORMATS, DIFF_FORMATS, designCommand;
+var init_design2 = __esm(() => {
+  init_esm();
+  init_design();
+  init_config();
+  init_from_db();
+  init_compare();
+  init_diff();
+  init_config_path();
+  VALIDATE_FORMATS = ["json", "markdown"];
+  RENDER_FORMATS = ["json", "markdown", "mermaid"];
+  DIFF_FORMATS = ["json", "table", "markdown"];
+  designCommand = new Command("design").description("Validate, render, and safely review a version-controlled SQL database design");
+  designCommand.command("init").description("Write an empty design artifact only to the explicitly supplied output path").requiredOption("--output <path>", "Path for the new design JSON artifact").option("--dialect <dialect>", "Target SQL dialect: postgresql, mysql, or mariadb", "postgresql").action(async (options) => {
+    try {
+      if (!["postgresql", "mysql", "mariadb"].includes(options.dialect)) {
+        throw new Error("dialect must be postgresql, mysql, or mariadb");
+      }
+      const file = Bun.file(options.output);
+      if (await file.exists())
+        throw new Error(`refusing to overwrite existing file: ${options.output}`);
+      await Bun.write(options.output, template(options.dialect));
+      console.log(JSON.stringify({ status: "created", path: options.output }, null, 2));
+    } catch (error) {
+      console.error(error.message);
+      process.exit(1);
+    }
+  });
+  designCommand.command("diff").description("Compare a valid design against the local schema cache or local ORM definition without connecting").option("--file <path>", "Design JSON file (default: dbcli.design.json)").option("--against-cache", "Compare against the configured local schema cache").option("--against-orm <paths>", "Compare against ORM definition(s), repeatable or comma-separated; DDL supports globs", collectOption2, []).option("--orm-format <format>", "Force ORM input: prisma | ddl | json | drizzle | typeorm | sequelize").option("--ignore <globs>", "Comma-separated table globs excluded from drift").option("--format <format>", "Output format: json, table, or markdown", "json").action(async (options, command) => {
+    const format = options.format;
+    if (!isFormat(format, DIFF_FORMATS))
+      throw new Error("format must be json, table, or markdown");
+    try {
+      const spec = await loadDesignSpec(defaultFile(options.file));
+      const review = reviewDesign(spec);
+      if (review.summary.errors > 0) {
+        console.log(formatDesignReview(review, format === "table" ? "markdown" : format));
+        process.exitCode = 1;
+        return;
+      }
+      const modeCount = Number(Boolean(options.againstCache)) + Number((options.againstOrm?.length ?? 0) > 0);
+      if (modeCount !== 1) {
+        throw new Error("Choose exactly one of --against-cache or --against-orm");
+      }
+      const desired = compileDesignSchema(spec);
+      const ignore = parseIgnore(options.ignore);
+      const report = options.againstCache ? await compareAgainstCache(desired, spec.dialect, ignore, command) : await compareAgainstOrm(desired, spec.dialect, options.againstOrm ?? [], options.ormFormat, ignore);
+      console.log(formatDrift(report, format));
+      process.exitCode = report.summary.errors > 0 ? 1 : 0;
+    } catch (error) {
+      fail2(error, format === "table" ? "markdown" : format);
+    }
+  });
+  designCommand.command("propose").description("Produce a review-only migration proposal from design drift; never executes DDL").option("--file <path>", "Design JSON file (default: dbcli.design.json)").option("--against-cache", "Compare against the configured local schema cache").option("--against-orm <paths>", "Compare against ORM definition(s), repeatable or comma-separated; DDL supports globs", collectOption2, []).option("--orm-format <format>", "Force ORM input: prisma | ddl | json | drizzle | typeorm | sequelize").option("--ignore <globs>", "Comma-separated table globs excluded from drift").option("--format <format>", "Output format: json or markdown", "markdown").action(async (options, command) => {
+    const format = options.format;
+    if (!isFormat(format, VALIDATE_FORMATS))
+      throw new Error("format must be json or markdown");
+    try {
+      const spec = await loadDesignSpec(defaultFile(options.file));
+      const review = reviewDesign(spec);
+      if (review.summary.errors > 0) {
+        console.log(formatDesignReview(review, format));
+        process.exitCode = 1;
+        return;
+      }
+      const modeCount = Number(Boolean(options.againstCache)) + Number((options.againstOrm?.length ?? 0) > 0);
+      if (modeCount !== 1) {
+        throw new Error("Choose exactly one of --against-cache or --against-orm");
+      }
+      const desired = compileDesignSchema(spec);
+      const ignore = parseIgnore(options.ignore);
+      const report = options.againstCache ? await compareAgainstCache(desired, spec.dialect, ignore, command) : await compareAgainstOrm(desired, spec.dialect, options.againstOrm ?? [], options.ormFormat, ignore);
+      console.log(formatDesignProposal(planDesignProposals(report), format));
+      process.exitCode = report.summary.errors > 0 ? 1 : 0;
+    } catch (error) {
+      fail2(error, format);
+    }
+  });
+  designCommand.command("validate").description("Validate a local SQL design artifact without a database connection").option("--file <path>", "Design JSON file (default: dbcli.design.json)").option("--format <format>", "Output format: json or markdown", "json").action(async (options) => {
+    const format = options.format;
+    if (!isFormat(format, VALIDATE_FORMATS))
+      throw new Error("format must be json or markdown");
+    try {
+      const review = reviewDesign(await loadDesignSpec(defaultFile(options.file)));
+      console.log(formatDesignReview(review, format));
+      process.exitCode = review.summary.errors > 0 ? 1 : 0;
+    } catch (error) {
+      fail2(error, format);
+    }
+  });
+  designCommand.command("render").description("Render a valid local SQL design as JSON, Markdown, or Mermaid ERD").option("--file <path>", "Design JSON file (default: dbcli.design.json)").option("--format <format>", "Output format: json, markdown, or mermaid", "markdown").action(async (options) => {
+    const format = options.format;
+    if (!isFormat(format, RENDER_FORMATS))
+      throw new Error("format must be json, markdown, or mermaid");
+    try {
+      const spec = await loadDesignSpec(defaultFile(options.file));
+      const review = reviewDesign(spec);
+      if (review.summary.errors > 0) {
+        console.log(formatDesignReview(review, format === "mermaid" ? "markdown" : format));
+        process.exitCode = 1;
+        return;
+      }
+      console.log(formatDesign(spec, review, format));
+    } catch (error) {
+      fail2(error, format === "mermaid" ? "markdown" : format);
+    }
+  });
+});
+
 // src/core/backfill-artifact.ts
 import { createHash as createHash5 } from "crypto";
 function isRecord3(value) {
@@ -108360,6 +109105,13 @@ function parsePositiveInteger(value) {
   }
   return parsed;
 }
+function parseSlowMs(value) {
+  try {
+    return parseSlowQueryThreshold(value);
+  } catch {
+    throw new InvalidArgumentError("must be a non-negative integer");
+  }
+}
 function normalizeLimitFlags(options) {
   const limit = options.limit;
   if (typeof limit === "boolean") {
@@ -108396,7 +109148,7 @@ function buildProgram() {
   program2.addCommand(initCommand);
   program2.addCommand(listCommand);
   program2.addCommand(schemaCommand);
-  program2.command("query [sql]").description(t("query.description")).option("-f, --query-file <path>", "Read query text from a UTF-8 file, or - for stdin").option("--format <type>", "Output format: table, json, csv, html", "table").option("--ui", "Show interactive dashboard in browser", false).option("--limit <number>", "Limit result rows (overrides auto-limit)", parsePositiveInteger).option("--no-limit", "Disable auto-limit in query-only mode").option("--collection <name>", "MongoDB collection name; Elasticsearch index name").option("--index <name>", "Elasticsearch index name (alias for --collection)").option("--fields <list>", "Include fields, or exclude them with --fields=-field_a,-field_b").option("--truncate <number>", "Limit serialized table cells to N Unicode characters", parsePositiveInteger).option("--no-truncate", "Disable the default table-cell truncation").addOption(createConnectionSelectorOption()).option("--recovery", "On failure, emit a structured recovery envelope to stdout (suppresses human stderr message)", false).action(async (sql, options, command) => {
+  program2.command("query [sql]").description(t("query.description")).option("-f, --query-file <path>", "Read query text from a UTF-8 file, or - for stdin").option("--format <type>", "Output format: table, json, csv, html", "table").option("--ui", "Show interactive dashboard in browser", false).option("--limit <number>", "Limit result rows (overrides auto-limit)", parsePositiveInteger).option("--no-limit", "Disable auto-limit in query-only mode").option("--collection <name>", "MongoDB collection name; Elasticsearch index name").option("--index <name>", "Elasticsearch index name (alias for --collection)").option("--fields <list>", "Include fields, or exclude them with --fields=-field_a,-field_b").option("--truncate <number>", "Limit serialized table cells to N Unicode characters", parsePositiveInteger).option("--no-truncate", "Disable the default table-cell truncation").option("--slow-ms <number>", "Emit a passive performance hint at or above this execution time; 0 disables it", parseSlowMs, 1000).addOption(createConnectionSelectorOption()).option("--recovery", "On failure, emit a structured recovery envelope to stdout (suppresses human stderr message)", false).action(async (sql, options, command) => {
     const rawArgs = command.parent?.rawArgs ?? [];
     const rawTruncate = findLongOptionValue(rawArgs, "--truncate");
     const rootUse = command.parent?.opts().use;
@@ -108412,7 +109164,7 @@ function buildProgram() {
   program2.command("plan <sql>").description("Analyze SQL risk without executing").option("--format <type>", "Output format: text, json", "text").action(async (sql, options, command) => {
     await planCommand(sql, options, command);
   });
-  program2.command("q <name>").description(t("q.description")).option("--format <type>", "Output format: table, json, csv, html", "table").option("--ui", "Show interactive dashboard in browser", false).option("--no-limit", "Disable size guard wrap (LIMIT 1000)").option("--dry-run", "Show final SQL + bind values; do not execute").option("--param <kv>", "Pass parameter as key=value (repeatable)", (val, prev = []) => prev.concat([val]), []).option("--param-file <path>", "JSON file containing param values").option("--recovery", "On failure, emit a structured recovery envelope to stdout (suppresses human stderr message)", false).option("--verify", "Run verification check after execution if defined", false).action(async (name2, options, command) => {
+  program2.command("q <name>").description(t("q.description")).option("--format <type>", "Output format: table, json, csv, html", "table").option("--ui", "Show interactive dashboard in browser", false).option("--no-limit", "Disable size guard wrap (LIMIT 1000)").option("--dry-run", "Show final SQL + bind values; do not execute").option("--param <kv>", "Pass parameter as key=value (repeatable)", (val, prev = []) => prev.concat([val]), []).option("--param-file <path>", "JSON file containing param values").option("--slow-ms <number>", "Emit a passive performance hint at or above this execution time; 0 disables it", parseSlowMs, 1000).option("--recovery", "On failure, emit a structured recovery envelope to stdout (suppresses human stderr message)", false).option("--verify", "Run verification check after execution if defined", false).action(async (name2, options, command) => {
     await qCommand(name2, normalizeLimitFlags(options), command);
   });
   program2.command("insert <table>").description(t("insert.description")).option("--data <json>", "JSON object to insert").option("--dry-run", "Show generated SQL without executing").option("--force", "Skip confirmation prompt").option("--plan", "Analyze risk without connecting or executing").option("--format <type>", "Output format for --plan: text or json", "text").option("--recovery", "On failure, emit a structured recovery envelope to stdout (suppresses human stderr message)", false).action(async (table, options, command) => {
@@ -108482,6 +109234,7 @@ function buildProgram() {
   program2.addCommand(verifyCommand);
   program2.addCommand(proxyCommand);
   program2.addCommand(semanticCommand);
+  program2.addCommand(designCommand);
   program2.addCommand(backfillCommand);
   return program2;
 }
@@ -108526,10 +109279,12 @@ var init_program = __esm(() => {
   init_use();
   init_proxy();
   init_semantic2();
+  init_design2();
   init_backfill();
   init_connection_selector();
   init_cli_error();
   init_validation();
+  init_slow_query_advisory();
   init_package();
 });
 
@@ -108655,7 +109410,7 @@ async function claimUpdateHint(configPath, kind, sessionKey, value) {
 // src/cli.ts
 init_program();
 init_cli_error();
-import { join as join40 } from "path";
+import { join as join41 } from "path";
 import { writeSync as writeSync2 } from "fs";
 import { format } from "util";
 function installSynchronousRedirectedStdout() {
@@ -108784,7 +109539,7 @@ program2.hook("preAction", (thisCommand, actionCommand) => {
       try {
         let cache = null;
         try {
-          const cacheFile = Bun.file(join40(configPath, "version-check.json"));
+          const cacheFile = Bun.file(join41(configPath, "version-check.json"));
           if (await cacheFile.exists()) {
             cache = await cacheFile.json();
           }