@batadata/cli 0.1.11 → 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,6 +1,109 @@
+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
+ * `--project` would target the wrong project (the exact db-query bug this
+ * command must not repeat). Remaining positionals are returned in `rest`.
+ */
+export declare function parseSchemaDumpArgs(args: string[]): {
+    branch?: string;
+    projectId?: string;
+    rest: string[];
+};
+/**
+ * Pull `--project <id>` out of `schema diff` args, leaving the two positional
+ * branch refs (`<from> <to>`) in `rest`. Consuming the flag value keeps a
+ * `--project` from being mistaken for a branch ref.
+ */
+export declare function parseSchemaDiffArgs(args: string[]): {
+    projectId?: string;
+    rest: string[];
+};
 export declare function handleSchema(args: string[]): Promise<void>;
+export {};

package/dist/commands/schema.js

@@ -1,9 +1,9 @@
 import { readFileSync } from "node:fs";
 import { api, apiError } from "../api.js";
-import { requireToken, isJsonMode } from "../config.js";
+import { requireToken, isJsonMode, loadConfig } from "../config.js";
 import { colors, log, json, spinner, table, heading } from "../utils/logger.js";
-import { emitError } from "../utils/errors.js";
-import { resolveProjectId } from "../link.js";
+import { emitError, isRetryable } from "../utils/errors.js";
+import { resolveProjectId, resolveBranchId } from "../link.js";
 const NOT_IMPLEMENTED_HINT = "Use `bata schema check <file.sql> --fail-on breaking` to gate migrations today.";
 /**
  * Unimplemented schema subcommand. Never exits 0 for a no-op: emits the
@@ -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) {
@@ -178,38 +220,253 @@ function renderReport(v) {
         log(`  ${colors.dim(`· ${n}`)}`);
     log();
 }
+/**
+ * Pull `--branch <ref>` / `--project <id>` (and their `=`-joined forms) out of
+ * `schema dump` args. Both flags are VALUE-consuming: a silently-ignored
+ * `--project` would target the wrong project (the exact db-query bug this
+ * command must not repeat). Remaining positionals are returned in `rest`.
+ */
+export function parseSchemaDumpArgs(args) {
+    let branch;
+    let projectId;
+    const rest = [];
+    for (let i = 0; i < args.length; i++) {
+        const a = args[i];
+        if (a === "--branch")
+            branch = args[++i];
+        else if (a.startsWith("--branch="))
+            branch = a.slice("--branch=".length);
+        else if (a === "--project")
+            projectId = args[++i];
+        else if (a.startsWith("--project="))
+            projectId = a.slice("--project=".length);
+        else
+            rest.push(a);
+    }
+    return { branch, projectId, rest };
+}
+/**
+ * Pull `--project <id>` out of `schema diff` args, leaving the two positional
+ * branch refs (`<from> <to>`) in `rest`. Consuming the flag value keeps a
+ * `--project` from being mistaken for a branch ref.
+ */
+export function parseSchemaDiffArgs(args) {
+    let projectId;
+    const rest = [];
+    for (let i = 0; i < args.length; i++) {
+        const a = args[i];
+        if (a === "--project")
+            projectId = args[++i];
+        else if (a.startsWith("--project="))
+            projectId = a.slice("--project=".length);
+        else
+            rest.push(a);
+    }
+    return { projectId, rest };
+}
+/** List a project's branches (GET /v1/projects/:id). Null on lookup failure. */
+async function listProjectBranches(projectId, token, teamId) {
+    const query = {};
+    if (teamId)
+        query.team_id = teamId;
+    const res = await api.get(`/v1/projects/${projectId}`, token, query);
+    if (!res.ok)
+        return null;
+    return res.data.branches ?? [];
+}
+/**
+ * Resolve a `--branch <ref>` (id OR name) to a concrete branch id, or the
+ * project's primary branch when no ref is given. Agents pass the name they used
+ * with `db branch create`, so name resolution is mandatory (id-only 404s).
+ * Exits via emitError with BRANCH_NOT_FOUND when nothing matches.
+ */
+async function resolveBranchIdForSchema(projectId, token, teamId, ref) {
+    const branches = await listProjectBranches(projectId, token, teamId);
+    if (!branches) {
+        emitError("API_UNAVAILABLE", "Failed to list branches for this project.", "Check the project id and try again.");
+    }
+    if (ref) {
+        const match = branches.find((b) => b.id === ref || b.name === ref);
+        if (!match) {
+            emitError("BRANCH_NOT_FOUND", `Branch "${ref}" not found in this project.`, "List branches with: bata db branches --json");
+        }
+        return match.id;
+    }
+    const primary = branches.find((b) => b.isPrimary) ?? branches[0];
+    if (!primary) {
+        emitError("BRANCH_NOT_FOUND", "This project has no branches to introspect.", "Create one with: bata db branch create <name>");
+    }
+    return primary.id;
+}
+/** Shared handling for a failed schema/diff request: retryable → COMPUTE_STARTING (exit 6). */
+function failSchemaRequest(res, fallback) {
+    const body = res.data;
+    if (isRetryable({ status: res.status, code: body?.code, message: body?.error })) {
+        emitError("COMPUTE_STARTING", apiError(res, fallback), "compute is starting; retry in a few seconds");
+    }
+    const code = res.status === 401 || res.status === 403 ? "INVALID_KEY"
+        : res.status === 404 ? "NO_PROJECT"
+            : "CLI_ERROR";
+    emitError(code, apiError(res, fallback), "");
+}
+async function schemaDump(args) {
+    const jsonMode = isJsonMode();
+    const { branch: branchFlag, projectId: projectFlag } = parseSchemaDumpArgs(args);
+    const token = requireToken();
+    const config = loadConfig();
+    // Project precedence: --project flag > .batadata link > config default.
+    const projectId = resolveProjectId(projectFlag).projectId;
+    if (!projectId) {
+        emitError("NO_PROJECT", "No project for schema dump.", "Pass --project <id>, or run `bata link <project>` to set a default.");
+    }
+    // Branch precedence: explicit --branch wins, else the branch pinned by
+    // `bata db branch checkout`, else the project's primary branch.
+    const branchRef = resolveBranchId(branchFlag).branchId;
+    const s = jsonMode ? null : spinner("Introspecting schema");
+    const branchId = await resolveBranchIdForSchema(projectId, token, config.defaultTeam, branchRef);
+    const res = await api.get(`/v1/schema/${projectId}`, token, { branch_id: branchId });
+    s?.stop();
+    if (!res.ok)
+        failSchemaRequest(res, "Schema introspection failed");
+    if (jsonMode) {
+        json(res.data); // server payload is the source of truth
+        return;
+    }
+    renderSchema(res.data.branch_id, res.data.schema);
+}
+async function schemaDiff(args) {
+    const jsonMode = isJsonMode();
+    const { projectId: projectFlag, rest } = parseSchemaDiffArgs(args);
+    const [fromRef, toRef] = rest;
+    if (!fromRef || !toRef) {
+        emitError("MISSING_ARG", "Two branches are required.", "Usage: bata schema diff <from-branch> <to-branch> [--project <id>]");
+    }
+    const token = requireToken();
+    const config = loadConfig();
+    const projectId = resolveProjectId(projectFlag).projectId;
+    if (!projectId) {
+        emitError("NO_PROJECT", "No project for schema diff.", "Pass --project <id>, or run `bata link <project>` to set a default.");
+    }
+    const s = jsonMode ? null : spinner("Diffing branch schemas");
+    const fromId = await resolveBranchIdForSchema(projectId, token, config.defaultTeam, fromRef);
+    const toId = await resolveBranchIdForSchema(projectId, token, config.defaultTeam, toRef);
+    const res = await api.get(`/v1/schema/${projectId}/diff`, token, { from: fromId, to: toId });
+    s?.stop();
+    if (!res.ok)
+        failSchemaRequest(res, "Schema diff failed");
+    if (jsonMode) {
+        json(res.data);
+        return;
+    }
+    renderDiff(fromRef, toRef, res.data.diff);
+}
+function nullable(c) {
+    return c.isNullable ? "" : colors.dim(" NOT NULL");
+}
+function renderSchema(branchId, schema) {
+    heading("Schema");
+    log(`  ${colors.dim(`branch ${colors.cyan(branchId)} · ${schema.tables.length} table${schema.tables.length === 1 ? "" : "s"}`)}`);
+    log();
+    if (schema.tables.length === 0) {
+        log(`  ${colors.dim("No tables in this branch's schema.")}`);
+        log();
+        return;
+    }
+    for (const t of schema.tables) {
+        log(`  ${colors.bold(`${t.schema}.${t.name}`)}`);
+        for (const col of t.columns) {
+            const pk = col.isPrimaryKey ? colors.yellow(" PK") : "";
+            const def = col.defaultValue ? colors.dim(` = ${col.defaultValue}`) : "";
+            log(`    ${col.name} ${colors.cyan(col.dataType)}${nullable(col)}${pk}${def}`);
+        }
+        for (const idx of t.indexes) {
+            log(`    ${colors.dim(`index ${idx.name}`)}`);
+        }
+        for (const con of t.constraints) {
+            const fk = con.foreignTableName ? colors.dim(` -> ${con.foreignTableSchema}.${con.foreignTableName}.${con.foreignColumnName}`) : "";
+            log(`    ${colors.dim(`constraint ${con.name} (${con.type})`)}${fk}`);
+        }
+        log();
+    }
+}
+function renderDiff(fromRef, toRef, diff) {
+    heading("Schema diff");
+    log(`  ${colors.dim(`${colors.cyan(fromRef)} -> ${colors.cyan(toRef)}`)}`);
+    log();
+    if (diff.identical) {
+        log(`  ${colors.green(">")} Schemas are identical.`);
+        log();
+        return;
+    }
+    for (const t of diff.addedTables) {
+        log(`  ${colors.green("+ table")} ${colors.bold(`${t.schema}.${t.name}`)} ${colors.dim(`(${t.columns.length} columns)`)}`);
+    }
+    for (const t of diff.removedTables) {
+        log(`  ${colors.red("- table")} ${colors.bold(`${t.schema}.${t.name}`)}`);
+    }
+    for (const t of diff.changedTables) {
+        log(`  ${colors.yellow("~ table")} ${colors.bold(`${t.schema}.${t.name}`)}`);
+        for (const c of t.addedColumns)
+            log(`      ${colors.green(`+ column ${c.name} ${c.dataType}`)}`);
+        for (const c of t.removedColumns)
+            log(`      ${colors.red(`- column ${c.name}`)}`);
+        for (const c of t.changedColumns) {
+            const fields = c.changes.map((ch) => `${ch.field}: ${String(ch.from)} -> ${String(ch.to)}`).join(", ");
+            log(`      ${colors.yellow(`~ column ${c.name}`)} ${colors.dim(fields)}`);
+        }
+        for (const i of t.addedIndexes)
+            log(`      ${colors.green(`+ index ${i.name}`)}`);
+        for (const i of t.removedIndexes)
+            log(`      ${colors.red(`- index ${i.name}`)}`);
+        for (const i of t.changedIndexes)
+            log(`      ${colors.yellow(`~ index ${i.name}`)}`);
+        for (const con of t.addedConstraints)
+            log(`      ${colors.green(`+ constraint ${con.name} (${con.type})`)}`);
+        for (const con of t.removedConstraints)
+            log(`      ${colors.red(`- constraint ${con.name}`)}`);
+        for (const con of t.changedConstraints)
+            log(`      ${colors.yellow(`~ constraint ${con.name}`)}`);
+    }
+    log();
+}
 export async function handleSchema(args) {
     const sub = args[0];
     switch (sub) {
         case "check":
             return schemaCheck(args.slice(1));
+        case "dump":
+        case "show": // alias — the plan calls it `schema show`; `dump` is the agent-friendly verb
+            return schemaDump(args.slice(1));
+        case "diff":
+            return schemaDiff(args.slice(1));
         case "init":
             notImplemented("init");
         case "push":
             notImplemented("push");
         case "pull":
             notImplemented("pull");
-        case "diff":
-            notImplemented("diff");
         default:
             log();
             log(`  ${colors.bold("bata schema")} ${colors.dim("— schema safety & management")}`);
             log();
             log(`  ${colors.dim("Commands:")}`);
-            log(`    ${colors.cyan("check <file|->")}  Check a proposed DDL change against live query traffic`);
-            log(`    ${colors.cyan("init")}            Initialize schema from existing database ${colors.dim("(coming soon)")}`);
-            log(`    ${colors.cyan("push")}            Push schema changes to database ${colors.dim("(coming soon)")}`);
-            log(`    ${colors.cyan("pull")}            Pull schema from database ${colors.dim("(coming soon)")}`);
-            log(`    ${colors.cyan("diff")}            Show pending schema changes ${colors.dim("(coming soon)")}`);
+            log(`    ${colors.cyan("check <file|->")}          Check a proposed DDL change against live query traffic`);
+            log(`    ${colors.cyan("dump")}                    Dump a branch's live schema (tables, columns, indexes, constraints)`);
+            log(`    ${colors.cyan("diff <from> <to>")}        Diff two branches' schemas`);
+            log(`    ${colors.cyan("init")}                    Initialize schema from existing database ${colors.dim("(coming soon)")}`);
+            log(`    ${colors.cyan("push")}                    Push schema changes to database ${colors.dim("(coming soon)")}`);
+            log(`    ${colors.cyan("pull")}                    Pull schema from database ${colors.dim("(coming soon)")}`);
             log();
             log(`  ${colors.dim("Options:")}`);
-            log(`    ${colors.dim("--branch <id>      check against a branch's traffic")}`);
-            log(`    ${colors.dim("--window <1h|24h|7d|30d>   corpus window (default 24h)")}`);
+            log(`    ${colors.dim("--branch <name|id>          target a branch (dump; default: primary)")}`);
+            log(`    ${colors.dim("--project <id>              override the linked/default project")}`);
+            log(`    ${colors.dim("--json                      machine-readable output (dump/diff)")}`);
+            log(`    ${colors.dim("--window <1h|24h|7d|30d>    check corpus window (default 24h)")}`);
             log(`    ${colors.dim("--fail-on <breaking|risky>  exit 2 to gate CI (fail-closed: 'unknown' also trips)")}`);
             log();
             log(`  ${colors.dim("Examples:")}`);
-            log(`    ${colors.dim("bata schema check migration.sql")}`);
-            log(`    ${colors.dim('echo "ALTER TABLE orders DROP COLUMN status;" | bata schema check - --json')}`);
+            log(`    ${colors.dim("bata schema dump --branch main --json")}`);
+            log(`    ${colors.dim("bata schema diff main feature-x --json")}`);
             log(`    ${colors.dim("bata schema check migration.sql --fail-on breaking   # CI gate")}`);
             log();
     }

package/dist/commands/usage.d.ts

@@ -22,3 +22,17 @@ export declare function modelActionLabel(q: {
     model: string | null;
     action: string | null;
 }): string;
+/**
+ * Build the /turbine-queries request from `--by-query` flags. Exported + pure so
+ * the flag wiring is unit-testable — a flag that parses but is never forwarded
+ * (a silently-ignored flag) is an agent-usability bug, so we prove it here.
+ *
+ * Recognised: `--window <1h|24h|7d|30d>` (default 24h), `--branch <id>`,
+ * `--tag <label>` (Lever L2 — filter cost attribution to one query tag).
+ */
+export declare function buildByQueryRequest(args: string[]): {
+    timeRange: string;
+    branch?: string;
+    tag?: string;
+    query: Record<string, string>;
+};

package/dist/commands/usage.js

@@ -197,6 +197,25 @@ export function modelActionLabel(q) {
         return q.action;
     return colors.dim("raw");
 }
+/**
+ * Build the /turbine-queries request from `--by-query` flags. Exported + pure so
+ * the flag wiring is unit-testable — a flag that parses but is never forwarded
+ * (a silently-ignored flag) is an agent-usability bug, so we prove it here.
+ *
+ * Recognised: `--window <1h|24h|7d|30d>` (default 24h), `--branch <id>`,
+ * `--tag <label>` (Lever L2 — filter cost attribution to one query tag).
+ */
+export function buildByQueryRequest(args) {
+    const timeRange = parseValueFlag(args, "--window") ?? "24h";
+    const branch = parseValueFlag(args, "--branch");
+    const tag = parseValueFlag(args, "--tag");
+    const query = { timeRange, orderBy: "totalTime", limit: "20" };
+    if (branch)
+        query.branch_id = branch;
+    if (tag)
+        query.tag = tag;
+    return { timeRange, branch, tag, query };
+}
 async function usageByQuery(args) {
     const jsonMode = isJsonMode();
     const token = requireToken();
@@ -205,11 +224,7 @@ async function usageByQuery(args) {
     if (!projectId) {
         emitError("NO_PROJECT", "No project for --by-query.", "Pass --project <id>, or run `bata link <project>` to set a default.");
     }
-    const timeRange = parseValueFlag(args, "--window") ?? "24h";
-    const branch = parseValueFlag(args, "--branch");
-    const query = { timeRange, orderBy: "totalTime", limit: "20" };
-    if (branch)
-        query.branch_id = branch;
+    const { timeRange, branch, tag, query } = buildByQueryRequest(args);
     const s = jsonMode ? null : spinner("Attributing compute cost by query");
     const res = await api.get(`/v1/insights/${projectId}/turbine-queries`, token, query);
     s?.stop();
@@ -232,6 +247,7 @@ async function usageByQuery(args) {
             project_id: projectId,
             window: timeRange,
             branch_id: branch ?? null,
+            tag: tag ?? null,
             // Carry the basis so a consumer can always see HOW the estimate was made
             // and that it is off the billing path.
             cost_basis: {
@@ -245,6 +261,7 @@ async function usageByQuery(args) {
                 fingerprint: q.fingerprint,
                 model: q.model,
                 action: q.action,
+                tag: q.tag ?? null,
                 sql_template: q.sqlTemplate,
                 calls: q.calls,
                 mean_time_ms: q.meanTimeMs,
@@ -256,16 +273,22 @@ async function usageByQuery(args) {
         return;
     }
     heading("Cost by query — estimated");
-    log(`  ${colors.dim(`Project ${projectId} · window ${timeRange}${branch ? ` · branch ${branch}` : ""}`)}`);
+    log(`  ${colors.dim(`Project ${projectId} · window ${timeRange}${branch ? ` · branch ${branch}` : ""}${tag ? ` · tag ${tag}` : ""}`)}`);
     log();
     if (rows.length === 0) {
-        log(`  ${colors.dim("No ORM query traffic reported in this window.")}`);
-        log(`  ${colors.dim("Wire up createInsightsReporter() to start attributing cost.")}`);
+        if (tag) {
+            log(`  ${colors.dim(`No ORM query traffic tagged "${tag}" in this window.`)}`);
+        }
+        else {
+            log(`  ${colors.dim("No ORM query traffic reported in this window.")}`);
+            log(`  ${colors.dim("Wire up createInsightsReporter() to start attributing cost.")}`);
+        }
         log();
         return;
     }
-    table(["QUERY", "CALLS", "MEAN", "EST. COST"], rows.map((q) => [
+    table(["QUERY", "TAG", "CALLS", "MEAN", "EST. COST"], rows.map((q) => [
         modelActionLabel(q),
+        q.tag ?? colors.dim("—"),
         q.calls.toLocaleString(),
         `${q.meanTimeMs}ms`,
         estCost(q.estimatedCostCents),

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.11",
+  "version": "0.1.13",
   "description": "CLI for BataDB — serverless Postgres platform",
   "bin": {
     "bata": "./dist/index.js"