@batadata/cli 0.1.10 → 0.1.12

package/dist/commands/db.d.ts

@@ -38,5 +38,17 @@ export declare function branchSetProtected(ref: string | undefined, wantProtecte
  */
 export declare function branchCheckout(args: string[]): Promise<void>;
 export declare function studio(): Promise<void>;
+/**
+ * Pull `--branch <ref>` / `--at <ISO-timestamp|LSN>` flags (and their `=` forms)
+ * out of the query args and return them plus the remaining args, which join into
+ * the SQL string. Keeps `db query` order-independent (flags can sit before or
+ * after the SQL) and consistent with how global flags are parsed.
+ */
+export declare function parseQueryFlags(args: string[]): {
+    branchId?: string;
+    at?: string;
+    projectId?: string;
+    rest: string[];
+};
 export declare function query(args?: string[]): Promise<void>;
 export declare function handleDb(args: string[]): Promise<void>;

package/dist/commands/db.js

@@ -499,9 +499,10 @@ export async function studio() {
  * the SQL string. Keeps `db query` order-independent (flags can sit before or
  * after the SQL) and consistent with how global flags are parsed.
  */
-function parseQueryFlags(args) {
+export function parseQueryFlags(args) {
     let branchId;
     let at;
+    let projectId;
     const rest = [];
     for (let i = 0; i < args.length; i++) {
         const arg = args[i];
@@ -517,11 +518,17 @@ function parseQueryFlags(args) {
         else if (arg.startsWith("--at=")) {
             at = arg.slice("--at=".length);
         }
+        else if (arg === "--project") {
+            projectId = args[++i];
+        }
+        else if (arg.startsWith("--project=")) {
+            projectId = arg.slice("--project=".length);
+        }
         else {
             rest.push(arg);
         }
     }
-    return { branchId, at, rest };
+    return { branchId, at, projectId, rest };
 }
 /**
  * Resolve the branch a query should target: an explicit `--branch <id-or-name>`
@@ -621,7 +628,7 @@ async function runTimeTravelQuery(opts) {
 }
 export async function query(args = []) {
     const jsonMode = isJsonMode();
-    const { branchId: branchFlag, at, rest } = parseQueryFlags(args);
+    const { branchId: branchFlag, at, projectId: projectFlag, rest } = parseQueryFlags(args);
     // Branch precedence: an explicit --branch wins, else the branch pinned by
     // `bata db branch checkout` in .batadata/project.json, else the primary.
     const branchId = resolveBranchId(branchFlag).branchId;
@@ -631,9 +638,10 @@ export async function query(args = []) {
     }
     const token = requireToken();
     const config = loadConfig();
-    const projectId = resolveProjectId().projectId;
+    // Project precedence: --project flag > .batadata link > config default.
+    const projectId = resolveProjectId(projectFlag).projectId;
     if (!projectId) {
-        emitError("NO_PROJECT", "No default project set.", "Set one with: bata projects info <id>");
+        emitError("NO_PROJECT", "No project for db query.", "Pass --project <id>, or run `bata link <project>` to set a default.");
     }
     // `--at` is a time-travel query: fork a hidden ephemeral branch AS OF the point
     // and run the SQL there. Classify the point up front so a bad --at fails fast.

package/dist/commands/schema.d.ts

@@ -3,4 +3,24 @@ export declare function ormLabel(q: {
     model?: string | null;
     action?: string | null;
 }): string;
+/**
+ * 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>;

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
@@ -178,38 +178,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/package.json

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