@batadata/cli 0.1.12 → 0.1.13

package/dist/commands/migrate.js

@@ -1,6 +1,7 @@
 import { colors, log } from "../utils/logger.js";
 import { emitError } from "../utils/errors.js";
-const NOT_IMPLEMENTED_HINT = "Use `bata schema check <file.sql> --fail-on breaking` to gate migrations today.";
+import { schemaCheck } from "./schema.js";
+const NOT_IMPLEMENTED_HINT = "Use `bata migrate check <file.sql>` to gate migrations today.";
 /**
  * Unimplemented migrate subcommand. Never exits 0 for a no-op: emits the
  * NOT_IMPLEMENTED envelope (exit 3) so agents/CI see a real failure, with a
@@ -12,6 +13,12 @@ function notImplemented(cmd) {
 export async function handleMigrate(args) {
     const sub = args[0];
     switch (sub) {
+        case "check":
+            // The checker-gated-migration gate (L3): reuse the schema-check engine but
+            // default to failing on a breaking/unassessable change — a migration gate
+            // should be red by default, no flag required. `--fail-on risky` tightens
+            // it; there is no way to make the gate a no-op (that's `schema check`).
+            return schemaCheck(args.slice(1), { defaultFailOn: "breaking" });
         case "create":
             notImplemented("create");
         case "deploy":
@@ -25,13 +32,22 @@ export async function handleMigrate(args) {
             log(`  ${colors.bold("bata migrate")} ${colors.dim("— database migration management")}`);
             log();
             log(`  ${colors.dim("Commands:")}`);
-            log(`    ${colors.cyan("create")}   Create a new migration ${colors.dim("(not implemented)")}`);
-            log(`    ${colors.cyan("deploy")}   Deploy pending migrations ${colors.dim("(not implemented)")}`);
-            log(`    ${colors.cyan("status")}   Show migration status ${colors.dim("(not implemented)")}`);
-            log(`    ${colors.cyan("reset")}    Reset database ${colors.dim("(not implemented)")}`);
+            log(`    ${colors.cyan("check <file|->")}   Gate a migration against live query traffic ${colors.dim("(exit 2 if breaking)")}`);
+            log(`    ${colors.cyan("create")}          Create a new migration ${colors.dim("(not implemented)")}`);
+            log(`    ${colors.cyan("deploy")}          Deploy pending migrations ${colors.dim("(not implemented)")}`);
+            log(`    ${colors.cyan("status")}          Show migration status ${colors.dim("(not implemented)")}`);
+            log(`    ${colors.cyan("reset")}           Reset database ${colors.dim("(not implemented)")}`);
             log();
-            log(`  ${colors.yellow("!")} ${colors.dim("Migration commands are not yet implemented. To gate a migration today:")}`);
-            log(`    ${colors.cyan("bata schema check <file.sql> --fail-on breaking")}`);
+            log(`  ${colors.dim("Options (check):")}`);
+            log(`    ${colors.dim("--project <id>              gate a specific project (CI has no link)")}`);
+            log(`    ${colors.dim("--branch <name|id>          check against a branch's corpus")}`);
+            log(`    ${colors.dim("--window <1h|24h|7d|30d>    corpus window (default 24h)")}`);
+            log(`    ${colors.dim("--fail-on <breaking|risky>  threshold (default: breaking)")}`);
+            log(`    ${colors.dim("--json                      machine-readable verdict")}`);
+            log();
+            log(`  ${colors.dim("Examples:")}`);
+            log(`    ${colors.dim("bata migrate check migrations/0007.sql --project prj_123   # CI gate")}`);
+            log(`    ${colors.dim('cat change.sql | bata migrate check - --fail-on risky --json')}`);
             log();
     }
 }

package/dist/commands/schema.d.ts

@@ -1,8 +1,90 @@
+interface ImpactedQuery {
+    queryHash: string;
+    query: string;
+    calls: number;
+    meanTimeMs: number;
+    risk: "breaking" | "perf-risk";
+    reason: string;
+    model?: string | null;
+    action?: string | null;
+}
+interface Finding {
+    statement: string;
+    operation: string;
+    affected: {
+        table: string | null;
+        columns: string[];
+        index: string | null;
+        constraint: string | null;
+    };
+    risk: "breaking" | "risky" | "safe" | "unknown";
+    impactedQueries: ImpactedQuery[];
+    callsAtRisk: number;
+    suggestion?: string;
+    note?: string;
+}
+type GateVerdict = "pass" | "warn" | "fail";
+interface Verdict {
+    overallRisk: "breaking" | "risky" | "safe" | "unknown";
+    verdict?: GateVerdict;
+    summary: {
+        statements: number;
+        breakingCount: number;
+        riskyCount: number;
+        safeCount: number;
+        unknownCount: number;
+        totalCallsAtRisk: number;
+    };
+    corpus: {
+        windowHours: number;
+        queryShapes: number;
+        totalCalls: number;
+        branchId: string | null;
+        empty: boolean;
+        capped: boolean;
+    };
+    findings: Finding[];
+    notes: string[];
+}
+/**
+ * Fail-closed local mirror of the server's gate mapping: breaking/unknown →
+ * fail, risky → warn, safe → pass. Used only when the server omits `verdict`
+ * (older control-plane); otherwise the server value is authoritative.
+ */
+export declare function deriveVerdict(r: Verdict["overallRisk"]): GateVerdict;
+interface CheckArgs {
+    file?: string;
+    stdin: boolean;
+    branch?: string;
+    project?: string;
+    window: string;
+    failOn?: string;
+}
+/**
+ * Parse `schema check` / `migrate check` args, consuming flag VALUES so they
+ * can't be mistaken for the positional file path (e.g. `--branch main
+ * migration.sql` must not read a file called "main"). Every value-taking flag
+ * supports both the ` ` and `=` form. A silently-ignored `--project` would gate
+ * the WRONG project in CI — the exact `db query` bug this must not repeat — so
+ * it is consumed as a value here and tested.
+ */
+export declare function parseCheckArgs(args: string[]): CheckArgs;
 /** `model:action` when the shape came from the ORM corpus, else "—" (raw SQL). */
 export declare function ormLabel(q: {
     model?: string | null;
     action?: string | null;
 }): string;
+/**
+ * Options for the shared check flow.
+ *  - `defaultFailOn`: the gate threshold applied when the caller passes no
+ *    `--fail-on`. `bata schema check` is analysis-first (undefined → exit 0
+ *    always); `bata migrate check` is a GATE (`breaking` → exit 2 on a breaking
+ *    or unassessable change even with no flag).
+ */
+export interface SchemaCheckOptions {
+    defaultFailOn?: "breaking" | "risky";
+}
+export declare function schemaCheck(args: string[], opts?: SchemaCheckOptions): Promise<void>;
 /**
  * Pull `--branch <ref>` / `--project <id>` (and their `=`-joined forms) out of
  * `schema dump` args. Both flags are VALUE-consuming: a silently-ignored
@@ -24,3 +106,4 @@ export declare function parseSchemaDiffArgs(args: string[]): {
     rest: string[];
 };
 export declare function handleSchema(args: string[]): Promise<void>;
+export {};

package/dist/commands/schema.js

@@ -12,6 +12,18 @@ const NOT_IMPLEMENTED_HINT = "Use `bata schema check <file.sql> --fail-on breaki
 function notImplemented(cmd) {
     emitError("NOT_IMPLEMENTED", `Schema ${cmd} is not yet implemented.`, NOT_IMPLEMENTED_HINT);
 }
+/**
+ * Fail-closed local mirror of the server's gate mapping: breaking/unknown →
+ * fail, risky → warn, safe → pass. Used only when the server omits `verdict`
+ * (older control-plane); otherwise the server value is authoritative.
+ */
+export function deriveVerdict(r) {
+    if (r === "breaking" || r === "unknown")
+        return "fail";
+    if (r === "risky")
+        return "warn";
+    return "pass";
+}
 async function readStdin() {
     const chunks = [];
     for await (const chunk of process.stdin)
@@ -19,11 +31,14 @@ async function readStdin() {
     return Buffer.concat(chunks).toString("utf8");
 }
 /**
- * Parse `schema check` args, consuming flag VALUES so they can't be mistaken
- * for the positional file path (e.g. `--branch main migration.sql` must not
- * read a file called "main").
+ * Parse `schema check` / `migrate check` args, consuming flag VALUES so they
+ * can't be mistaken for the positional file path (e.g. `--branch main
+ * migration.sql` must not read a file called "main"). Every value-taking flag
+ * supports both the ` ` and `=` form. A silently-ignored `--project` would gate
+ * the WRONG project in CI — the exact `db query` bug this must not repeat — so
+ * it is consumed as a value here and tested.
  */
-function parseCheckArgs(args) {
+export function parseCheckArgs(args) {
     const out = { stdin: false, window: "24h" };
     for (let i = 0; i < args.length; i++) {
         const a = args[i];
@@ -31,20 +46,40 @@ function parseCheckArgs(args) {
             out.branch = args[++i];
             continue;
         }
+        if (a.startsWith("--branch=")) {
+            out.branch = a.slice("--branch=".length);
+            continue;
+        }
+        if (a === "--project") {
+            out.project = args[++i];
+            continue;
+        }
+        if (a.startsWith("--project=")) {
+            out.project = a.slice("--project=".length);
+            continue;
+        }
         if (a === "--window") {
             out.window = args[++i] ?? out.window;
             continue;
         }
+        if (a.startsWith("--window=")) {
+            out.window = a.slice("--window=".length) || out.window;
+            continue;
+        }
         if (a === "--fail-on") {
             out.failOn = args[++i];
             continue;
         }
+        if (a.startsWith("--fail-on=")) {
+            out.failOn = a.slice("--fail-on=".length);
+            continue;
+        }
         if (a === "-") {
             out.stdin = true;
             continue;
         }
         if (a.startsWith("-"))
-            continue; // unknown/global flag already handled upstream
+            continue; // unknown/global flag (e.g. --json) handled upstream
         if (out.file === undefined)
             out.file = a;
     }
@@ -74,13 +109,16 @@ function affectedLabel(a) {
         return a.table;
     return "—";
 }
-async function schemaCheck(args) {
+export async function schemaCheck(args, opts = {}) {
     const jsonMode = isJsonMode();
-    const { file, stdin, branch: branchId, window: timeRange, failOn } = parseCheckArgs(args);
+    const { file, stdin, branch: branchId, project: projectFlag, window: timeRange, failOn: failOnArg } = parseCheckArgs(args);
     // Reject a typo'd --fail-on value rather than silently disabling the gate.
-    if (failOn !== undefined && failOn !== "breaking" && failOn !== "risky") {
-        emitError("INVALID_FLAG", `Invalid --fail-on value "${failOn}".`, "Use --fail-on breaking or --fail-on risky.");
+    if (failOnArg !== undefined && failOnArg !== "breaking" && failOnArg !== "risky") {
+        emitError("INVALID_FLAG", `Invalid --fail-on value "${failOnArg}".`, "Use --fail-on breaking or --fail-on risky.");
     }
+    // An explicit --fail-on always wins; otherwise fall back to the command's
+    // default gate (set for `migrate check`, unset for `schema check`).
+    const failOn = failOnArg ?? opts.defaultFailOn;
     // ── read DDL (file path, explicit "-", or piped stdin) ──
     let ddl;
     try {
@@ -101,10 +139,11 @@ async function schemaCheck(args) {
         emitError("EMPTY_INPUT", "DDL input was empty.", "Provide a schema change to check, e.g. ALTER TABLE orders DROP COLUMN status;");
     }
     const token = requireToken();
-    // Precedence: .batadata link > config default (schema check has no --project).
-    const projectId = resolveProjectId().projectId;
+    // Precedence: --project flag > .batadata link > config default. CI runners
+    // rarely have a committed link, so an explicit --project is the reliable path.
+    const projectId = resolveProjectId(projectFlag).projectId;
     if (!projectId) {
-        emitError("NO_PROJECT", "No default project set.", "Run `bata link <project>` or set a default with: bata projects info <id>");
+        emitError("NO_PROJECT", "No project for schema check.", "Pass --project <id>, run `bata link <project>`, or set a default project.");
     }
     const body = { sql: ddl, timeRange };
     if (branchId)
@@ -127,12 +166,15 @@ async function schemaCheck(args) {
         renderReport(v);
     }
     // Exit 0 on a successful analysis (risk lives in the payload). --fail-on gates
-    // for CI and is FAIL-CLOSED: `unknown` (the checker couldn't assess the change,
-    // e.g. TRUNCATE / DROP SCHEMA) trips BOTH thresholds, so a gate never goes
-    // green on an unassessable-but-dangerous migration.
-    if (failOn === "breaking" && (v.overallRisk === "breaking" || v.overallRisk === "unknown"))
+    // for CI on the machine-decidable verdict and is FAIL-CLOSED: `fail` covers
+    // both breaking AND unknown (the checker couldn't assess the change, e.g.
+    // TRUNCATE / DROP SCHEMA), so a gate never goes green on an
+    // unassessable-but-dangerous migration. Fall back to a local derivation when
+    // an older server omits `verdict`.
+    const gate = v.verdict ?? deriveVerdict(v.overallRisk);
+    if (failOn === "breaking" && gate === "fail")
         process.exit(2);
-    if (failOn === "risky" && v.overallRisk !== "safe")
+    if (failOn === "risky" && gate !== "pass")
         process.exit(2);
 }
 function renderReport(v) {

package/dist/index.js

@@ -61,8 +61,8 @@ function help() {
     log(`  ${colors.bold("Schema & Types")}`);
     log(`    ${colors.cyan("generate")}           Generate types from database schema`);
     log(`    ${colors.cyan("generate --watch")}   Watch mode for type generation`);
-    log(`    ${colors.cyan("schema")}             Schema management ${colors.dim("(coming soon)")}`);
-    log(`    ${colors.cyan("migrate")}            Migration management ${colors.dim("(coming soon)")}`);
+    log(`    ${colors.cyan("schema check|dump|diff")}  Schema safety gate + introspection`);
+    log(`    ${colors.cyan("migrate check")}      Gate a migration against live query traffic ${colors.dim("(exit 2 if breaking)")}`);
     log();
     log(`  ${colors.bold("Development")}`);
     log(`    ${colors.cyan("dev")}                Local development setup guide`);
@@ -79,7 +79,7 @@ function help() {
     log(`    ${colors.dim("Every command works with just")} ${colors.cyan("BATA_API_KEY")} ${colors.dim("set — no login needed.")}`);
     log(`    ${colors.dim("Mint a key with")} ${colors.cyan("bata api-keys create --json")}${colors.dim(".")}`);
     log();
-    log(`    ${colors.cyan("schema check <file.sql> --fail-on breaking")}  Gate a migration (exit 2 if breaking)`);
+    log(`    ${colors.cyan("migrate check <file.sql> --project <id>")}     Gate a migration in CI (exit 2 if breaking)`);
     log(`    ${colors.cyan("db url --json")}                               Print connection string as JSON`);
     log(`    ${colors.cyan("db query <sql> --json")}                       Run SQL headlessly, rows as JSON objects`);
     log(`    ${colors.cyan("usage --json")}                                Per-dimension cost (honest: un-metered → null)`);
@@ -90,7 +90,7 @@ function help() {
     log(`  ${colors.bold("Exit codes")}`);
     log(`    ${colors.dim("0")}  success`);
     log(`    ${colors.dim("1")}  generic error ${colors.dim("(CLI_ERROR)")}`);
-    log(`    ${colors.dim("2")}  gate tripped ${colors.dim("(schema check --fail-on)")}`);
+    log(`    ${colors.dim("2")}  gate tripped ${colors.dim("(migrate/schema check --fail-on)")}`);
     log(`    ${colors.dim("3")}  not implemented ${colors.dim("(NOT_IMPLEMENTED)")}`);
     log(`    ${colors.dim("4")}  auth / credentials ${colors.dim("(NO_CREDENTIALS, INVALID_KEY)")}`);
     log(`    ${colors.dim("5")}  not-found / bad input ${colors.dim("(NO_PROJECT, BRANCH_NOT_FOUND, INVALID_FLAG, INTERACTIVE_ONLY)")}`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@batadata/cli",
-  "version": "0.1.12",
+  "version": "0.1.13",
   "description": "CLI for BataDB — serverless Postgres platform",
   "bin": {
     "bata": "./dist/index.js"