@batadata/cli 0.1.9 → 0.1.11

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

@@ -7,6 +7,9 @@ import { prompt, confirmDestructive } from "../utils/prompts.js";
 import { openBrowser } from "../utils/open.js";
 import { emitError, isRetryable } from "../utils/errors.js";
 import { resolveProjectId, resolveBranchId, findLinkFile, writeLinkFile } from "../link.js";
+// Share the exact LSN/timestamp discriminator `bata restore` uses so `db query
+// --at` classifies a restore point identically.
+import { classifyRestorePoint } from "./restore.js";
 async function getConnectionInfo(projectId, token) {
     // reveal=true so the returned string is actually usable (the owner is asking).
     const res = await api.get(`/v1/connection-info/${projectId}`, token, { reveal: "true" });
@@ -491,14 +494,15 @@ export async function studio() {
     openBrowser(studioUrl);
 }
 /**
- * Pull a `--branch <ref>` / `--branch=<ref>` flag out of the query args and
- * return the explicit branch ref — an id OR a name, resolved later — plus the
- * remaining args, which join into the SQL string. Keeps `db query`
- * order-independent (the flag can sit before or after the SQL) and consistent
- * with how global flags are parsed.
+ * 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.
  */
-function parseBranchFlag(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];
@@ -508,15 +512,123 @@ function parseBranchFlag(args) {
         else if (arg.startsWith("--branch=")) {
             branchId = arg.slice("--branch=".length);
         }
+        else if (arg === "--at") {
+            at = args[++i];
+        }
+        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, rest };
+    return { branchId, at, projectId, rest };
+}
+/**
+ * Resolve the branch a query should target: an explicit `--branch <id-or-name>`
+ * (resolved against the project's branch list) or the project's primary branch.
+ * Exits (via emitError) with BRANCH_NOT_FOUND if nothing matches.
+ */
+async function resolveQueryBranchId(projectId, token, teamId, branchRef) {
+    if (branchRef) {
+        const branch = await resolveBranchRef(projectId, token, teamId, branchRef);
+        if (!branch) {
+            emitError("BRANCH_NOT_FOUND", `Branch "${branchRef}" not found in this project.`, "List branches with: bata db branches --json");
+        }
+        return branch.id;
+    }
+    const branch = await getPrimaryBranch(projectId, token, teamId);
+    if (!branch) {
+        emitError("BRANCH_NOT_FOUND", "No branch found for this project to run the query against.", "Check the project with: bata db branches --json");
+    }
+    return branch.id;
+}
+/**
+ * Run a time-travel query: POST /v1/time-travel/query, which forks a hidden
+ * ephemeral branch AS OF the point and runs the SQL there. Handles the cold-fork
+ * 503 contract — the response always carries the ephemeral `branch` handle so an
+ * agent can back off (exit 6) and retry the query itself via
+ * `bata db query <sql> --branch <returned-id>`.
+ */
+async function runTimeTravelQuery(opts) {
+    const { projectId, branchId, point, sql, token, jsonMode } = opts;
+    const s = jsonMode ? null : spinner(`Running query as of ${point.raw}`);
+    const res = await api.post("/v1/time-travel/query", { project_id: projectId, branch_id: branchId, at: point.value, query: sql }, token);
+    s?.stop();
+    if (!res.ok) {
+        const body = res.data;
+        // Cold fork: the ephemeral branch is still starting. Retryable (exit 6). The
+        // branch handle rides along so the agent can retry against it via /v1/sql.
+        if (isRetryable({ status: res.status, code: body?.code, message: body?.error })) {
+            if (jsonMode) {
+                json({
+                    error: apiError(res, "Time-travel branch is starting"),
+                    code: body?.code ?? "COMPUTE_STARTING",
+                    hint: "retry the query against the returned branch: bata db query <sql> --branch <branch.id>",
+                    branch: body?.branch ?? null,
+                });
+                process.exit(6);
+            }
+            emitError("COMPUTE_STARTING", apiError(res, "Time-travel branch is starting"), body?.branch
+                ? `compute is starting; retry in a few seconds with --branch ${body.branch.id}`
+                : "compute is starting; retry in a few seconds");
+        }
+        const code = res.status === 401 || res.status === 403 ? "INVALID_KEY" : "CLI_ERROR";
+        emitError(code, apiError(res, "Time-travel query failed"), "");
+    }
+    // The route returns an error field only on a real failure it couldn't map to a
+    // status; treat it as an error, not a silent success.
+    if (res.data.error) {
+        emitError("CLI_ERROR", res.data.error, "");
+    }
+    const columns = res.data.columns ?? [];
+    const rows = res.data.rows ?? [];
+    const rowCount = res.data.rowCount ?? rows.length;
+    const branch = res.data.branch ?? null;
+    if (jsonMode) {
+        json({
+            columns,
+            rows,
+            row_count: rowCount,
+            command: res.data.command ?? null,
+            at: point.value,
+            // The ephemeral branch the query ran against (auto-reaped after ~10 min).
+            branch,
+        });
+        return;
+    }
+    if (columns.length && rows.length) {
+        log();
+        table(columns.map((c) => c.toUpperCase()), rows.map((r) => columns.map((col) => fmtCell(r[col]))));
+        log();
+        log(`  ${colors.dim(`${rowCount} row(s) — as of ${point.raw}`)}`);
+    }
+    else if (rows.length) {
+        const keys = Object.keys(rows[0]);
+        log();
+        table(keys.map((k) => k.toUpperCase()), rows.map((r) => keys.map((k) => fmtCell(r[k]))));
+        log();
+        log(`  ${colors.dim(`${rowCount} row(s) — as of ${point.raw}`)}`);
+    }
+    else {
+        log();
+        const cmd = res.data.command ? `${res.data.command} ` : "";
+        log(`  ${colors.dim(`${cmd}OK — ${rowCount} row(s), as of ${point.raw}.`)}`);
+    }
+    if (branch) {
+        log(`  ${colors.dim(`Ran on ephemeral branch ${branch.id} (auto-deleted ~${new Date(branch.expires_at).toLocaleTimeString()}).`)}`);
+    }
+    log();
 }
 export async function query(args = []) {
     const jsonMode = isJsonMode();
-    const { branchId: branchFlag, rest } = parseBranchFlag(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;
@@ -526,9 +638,28 @@ 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.
+    if (at !== undefined) {
+        const classified = classifyRestorePoint(at);
+        if (classified.error) {
+            emitError("INVALID_FLAG", classified.error, "Pass --at <ISO-timestamp|LSN> (an LSN looks like 0/15994B0).");
+        }
+        // Resolve the SOURCE branch to fork from (id or name), like the normal path.
+        const sourceBranchId = await resolveQueryBranchId(projectId, token, config.defaultTeam, branchId);
+        return runTimeTravelQuery({
+            projectId,
+            branchId: sourceBranchId,
+            point: classified.point,
+            sql,
+            token,
+            jsonMode,
+        });
     }
     const s = jsonMode ? null : spinner("Running query");
     // Target branch: an explicit --branch <id-or-name> wins; otherwise resolve
@@ -632,12 +763,15 @@ function dbHelp(sub) {
             log(`  ${colors.bold("bata db query")} — run a SQL query against a branch`);
             log();
             usage('bata db query "SELECT 1"');
-            usage("bata db query <sql> [--branch <id-or-name>] [--json]");
+            usage("bata db query <sql> [--branch <id-or-name>] [--at <timestamp|LSN>] [--json]");
             log();
             note("--branch <id-or-name>  Target a specific branch by id OR name (default: the project's primary)");
+            note("--at <timestamp|LSN>   Time-travel: run the query AS OF a past point (ISO-8601");
+            note("                       timestamp e.g. 2026-07-04T12:00:00Z, or an LSN e.g. 0/15994B0).");
+            note("                       Forks a hidden ephemeral branch (auto-deleted ~10 min).");
             note("--json                 Emit rows as JSON objects + row_count");
-            note("Cold-start note: a just-created/idle branch may answer with exit 6");
-            note("(retryable) while its compute wakes — retry in a few seconds.");
+            note("Cold-start note: a just-created/idle branch (or a fresh --at fork) may answer");
+            note("with exit 6 (retryable) while its compute wakes — retry in a few seconds.");
             break;
         case "branches":
             log(`  ${colors.bold("bata db branches")} — list branches and their compute status`);

package/dist/commands/schema.d.ts

@@ -1 +1,6 @@
+/** `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;
 export declare function handleSchema(args: string[]): Promise<void>;

package/dist/commands/schema.js

@@ -53,6 +53,16 @@ function parseCheckArgs(args) {
 const riskColor = (r) => r === "breaking" ? colors.red(r.toUpperCase())
     : r === "risky" || r === "unknown" ? colors.yellow(r.toUpperCase())
         : colors.green(r.toUpperCase());
+/** `model:action` when the shape came from the ORM corpus, else "—" (raw SQL). */
+export function ormLabel(q) {
+    if (q.model && q.action)
+        return `${q.model}:${q.action}`;
+    if (q.model)
+        return q.model;
+    if (q.action)
+        return q.action;
+    return "—";
+}
 function affectedLabel(a) {
     if (a.index)
         return `index ${a.index}`;
@@ -145,8 +155,11 @@ function renderReport(v) {
         log(`    ${colors.dim(f.statement)}`);
         if (f.impactedQueries.length) {
             const shown = f.impactedQueries.slice(0, 8);
-            table(["QUERY", "CALLS", "MEAN", "RISK"], shown.map((q) => [
-                q.query.length > 60 ? q.query.slice(0, 57) + "…" : q.query,
+            // Show model:action (from the ORM corpus) when present — the differentiator
+            // over raw pg_stat_statements shapes, which have no ORM semantics ("—").
+            table(["MODEL:ACTION", "QUERY", "CALLS", "MEAN", "RISK"], shown.map((q) => [
+                ormLabel(q),
+                q.query.length > 48 ? q.query.slice(0, 45) + "…" : q.query,
                 q.calls.toLocaleString(),
                 `${q.meanTimeMs}ms`,
                 q.risk,

package/dist/commands/usage.d.ts

@@ -11,3 +11,14 @@
  *   We will only show a dollar figure for a dimension we genuinely meter.
  */
 export declare function usage(args: string[]): Promise<void>;
+/**
+ * Format an estimated cost for human output. Cost-truth: `null` means "no
+ * compute metered", rendered as "not metered yet" — NEVER "$0.00" (that would
+ * read as a real priced zero). A sub-cent but non-zero estimate is "<$0.01" so
+ * it never collapses to $0.00; sub-dollar keeps 4dp to preserve fractional cents.
+ */
+export declare function estCost(cents: number | null): string;
+export declare function modelActionLabel(q: {
+    model: string | null;
+    action: string | null;
+}): string;

package/dist/commands/usage.js

@@ -14,6 +14,7 @@ import { api, apiError } from "../api.js";
 import { requireToken, isJsonMode } from "../config.js";
 import { colors, log, json, spinner, table, heading, kvList } from "../utils/logger.js";
 import { emitError } from "../utils/errors.js";
+import { resolveProjectId } from "../link.js";
 /**
  * Decide whether a dimension is truly metered. A dimension is metered only when
  * the API explicitly says so (`metered === true`). A missing `metered` field is
@@ -44,15 +45,24 @@ function valueLabel(d) {
     return `${d.value} ${d.unit}`;
 }
 function parseProjectFlag(args) {
+    return parseValueFlag(args, "--project");
+}
+/** Read `--name value` or `--name=value`; undefined if absent. */
+function parseValueFlag(args, name) {
+    const eq = `${name}=`;
     for (let i = 0; i < args.length; i++) {
-        if (args[i] === "--project" && args[i + 1])
+        if (args[i] === name && args[i + 1])
             return args[i + 1];
-        if (args[i].startsWith("--project="))
-            return args[i].slice("--project=".length);
+        if (args[i].startsWith(eq))
+            return args[i].slice(eq.length);
     }
     return undefined;
 }
 export async function usage(args) {
+    // `--by-query` is a per-project cost-attribution view (Lever L1): which ORM
+    // queries drive the project's compute bill. It's estimated, not metered.
+    if (args.includes("--by-query"))
+        return usageByQuery(args);
     const jsonMode = isJsonMode();
     const token = requireToken();
     const projectFilter = parseProjectFlag(args);
@@ -162,3 +172,112 @@ export async function usage(args) {
         log();
     }
 }
+/**
+ * Format an estimated cost for human output. Cost-truth: `null` means "no
+ * compute metered", rendered as "not metered yet" — NEVER "$0.00" (that would
+ * read as a real priced zero). A sub-cent but non-zero estimate is "<$0.01" so
+ * it never collapses to $0.00; sub-dollar keeps 4dp to preserve fractional cents.
+ */
+export function estCost(cents) {
+    if (cents === null)
+        return colors.dim("not metered yet");
+    if (cents <= 0)
+        return "$0.00";
+    const d = cents / 100;
+    if (d < 0.01)
+        return "<$0.01";
+    return `$${d.toFixed(d < 1 ? 4 : 2)}`;
+}
+export function modelActionLabel(q) {
+    if (q.model && q.action)
+        return `${q.model}.${q.action}`;
+    if (q.model)
+        return q.model;
+    if (q.action)
+        return q.action;
+    return colors.dim("raw");
+}
+async function usageByQuery(args) {
+    const jsonMode = isJsonMode();
+    const token = requireToken();
+    // Project precedence: --project flag > .batadata link > config default.
+    const { projectId } = resolveProjectId(parseProjectFlag(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 s = jsonMode ? null : spinner("Attributing compute cost by query");
+    const res = await api.get(`/v1/insights/${projectId}/turbine-queries`, token, query);
+    s?.stop();
+    if (!res.ok) {
+        emitError(res.status === 401 || res.status === 403 ? "INVALID_KEY"
+            : res.status === 404 ? "NO_PROJECT"
+                : res.status >= 500 || res.status === 0 ? "API_UNAVAILABLE"
+                    : "CLI_ERROR", apiError(res, "Failed to fetch per-query cost"), "");
+    }
+    const rows = res.data?.queries ?? [];
+    const basis = res.data?.costBasis ?? {
+        method: "no-compute-metered",
+        windowCuMs: 0,
+        windowComputeCents: null,
+        windowTotalTimeMs: 0,
+    };
+    const notMetered = basis.method === "no-compute-metered";
+    if (jsonMode) {
+        json({
+            project_id: projectId,
+            window: timeRange,
+            branch_id: branch ?? 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: {
+                method: basis.method,
+                estimated: true,
+                window_cu_ms: basis.windowCuMs,
+                window_compute_cents: basis.windowComputeCents,
+                window_total_time_ms: basis.windowTotalTimeMs,
+            },
+            queries: rows.map((q) => ({
+                fingerprint: q.fingerprint,
+                model: q.model,
+                action: q.action,
+                sql_template: q.sqlTemplate,
+                calls: q.calls,
+                mean_time_ms: q.meanTimeMs,
+                time_share: q.costTimeShare,
+                // null (not 0) when nothing was metered — never a priced $0.
+                estimated_cost_cents: q.estimatedCostCents,
+            })),
+        });
+        return;
+    }
+    heading("Cost by query — estimated");
+    log(`  ${colors.dim(`Project ${projectId} · window ${timeRange}${branch ? ` · branch ${branch}` : ""}`)}`);
+    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.")}`);
+        log();
+        return;
+    }
+    table(["QUERY", "CALLS", "MEAN", "EST. COST"], rows.map((q) => [
+        modelActionLabel(q),
+        q.calls.toLocaleString(),
+        `${q.meanTimeMs}ms`,
+        estCost(q.estimatedCostCents),
+    ]));
+    log();
+    // Honest footer: never let the estimate masquerade as a metered charge.
+    if (notMetered) {
+        log(`  ${colors.yellow("!")} ${colors.dim("No compute metered in this window — cost can't be attributed to queries yet (never shown as $0).")}`);
+    }
+    else {
+        log(`  ${colors.bold("Window compute:")} ${estCost(basis.windowComputeCents)} ${colors.dim("total (metered)")}`);
+        log(`  ${colors.dim("Per-query figures are ESTIMATES — Turbine insights are off the billing path; compute is apportioned by each query's share of ORM wall-time.")}`);
+    }
+    log();
+}

package/dist/index.js

@@ -83,6 +83,7 @@ function help() {
     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)`);
+    log(`    ${colors.cyan("usage --by-query [--project <id>] [--json]")}   Estimated compute cost per ORM query (off billing path)`);
     log();
     log(`    ${colors.dim("All errors in --json mode share one envelope:")} ${colors.dim('{ "error", "code", "hint" }')} ${colors.dim("on stderr.")}`);
     log();

package/package.json

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