@batadata/cli 0.1.1 → 0.1.2

package/dist/commands/migrate.js

@@ -1,37 +1,37 @@
-import { colors, log, heading } from "../utils/logger.js";
-function comingSoon(cmd) {
-    heading(`Migrate: ${cmd}`);
-    log(`  ${colors.yellow("!")} ${colors.dim("Coming soon.")} Migrations are not yet implemented.`);
-    log();
-    log(`  ${colors.dim("Track progress at")} ${colors.cyan("https://github.com/zvndev")}`);
-    log();
+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.";
+/**
+ * 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
+ * hint pointing at the migration-gating capability that exists today.
+ */
+function notImplemented(cmd) {
+    emitError("NOT_IMPLEMENTED", `Migrate ${cmd} is not yet implemented.`, NOT_IMPLEMENTED_HINT);
 }
 export async function handleMigrate(args) {
     const sub = args[0];
     switch (sub) {
         case "create":
-            comingSoon("create");
-            break;
+            notImplemented("create");
         case "deploy":
-            comingSoon("deploy");
-            break;
+            notImplemented("deploy");
         case "status":
-            comingSoon("status");
-            break;
+            notImplemented("status");
         case "reset":
-            comingSoon("reset");
-            break;
+            notImplemented("reset");
         default:
             log();
             log(`  ${colors.bold("bata migrate")} ${colors.dim("— database migration management")}`);
             log();
             log(`  ${colors.dim("Commands:")}`);
-            log(`    ${colors.cyan("create")}   Create a new migration`);
-            log(`    ${colors.cyan("deploy")}   Deploy pending migrations`);
-            log(`    ${colors.cyan("status")}   Show migration status`);
-            log(`    ${colors.cyan("reset")}    Reset database (dangerous)`);
+            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("All migration commands are coming soon.")}`);
+            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();
     }
 }

package/dist/commands/projects.js

@@ -1,7 +1,8 @@
 import { api, apiError, resolveTeamId, asList } from "../api.js";
 import { requireToken, loadConfig, saveConfig, isJsonMode } from "../config.js";
-import { colors, log, json, success, error, spinner, table, kvList, heading } from "../utils/logger.js";
-import { prompt, confirm, select } from "../utils/prompts.js";
+import { colors, log, json, success, spinner, table, kvList, heading } from "../utils/logger.js";
+import { prompt, confirmDestructive, select } from "../utils/prompts.js";
+import { emitError } from "../utils/errors.js";
 function projectCreatedAt(p) {
     return p.created_at ?? p.createdAt ?? "";
 }
@@ -38,18 +39,19 @@ export async function list() {
     const config = loadConfig();
     const jsonMode = isJsonMode();
     const s = jsonMode ? null : spinner("Fetching projects");
+    // GET /v1/projects requires a team_id — resolve it identically to `create`
+    // (falls back to the user's first team) so the API-key path doesn't 400.
     const teamId = await resolveTeamId(token);
-    const query = {};
-    if (teamId)
-        query.team_id = teamId;
-    const res = await api.get("/v1/projects", token, query);
+    if (!teamId) {
+        s?.stop();
+        emitError("NO_TEAM", "No team found for this credential.", "This API key isn't attached to a team. Run `bata login` or check `bata whoami`.");
+    }
+    const res = await api.get("/v1/projects", token, { team_id: teamId });
     if (!res.ok) {
         s?.stop();
-        if (jsonMode)
-            json({ error: apiError(res, "Failed to fetch projects") });
-        else
-            error(apiError(res, "Failed to fetch projects"));
-        process.exit(1);
+        emitError(res.status === 401 || res.status === 403 ? "INVALID_KEY"
+            : res.status >= 500 || res.status === 0 ? "API_UNAVAILABLE"
+                : "CLI_ERROR", apiError(res, "Failed to fetch projects"), "");
     }
     s?.stop();
     const projects = asList(res.data);
@@ -88,8 +90,7 @@ export async function create() {
     heading("Create a new project");
     const name = await prompt("Project name");
     if (!name) {
-        error("Project name is required.");
-        process.exit(1);
+        emitError("MISSING_ARG", "Project name is required.", "");
     }
     const region = await select("Select a region", REGIONS);
     const s = spinner("Creating project");
@@ -101,8 +102,9 @@ export async function create() {
     const res = await api.post("/v1/projects", body, token);
     if (!res.ok) {
         s.stop();
-        error(apiError(res, "Failed to create project"));
-        process.exit(1);
+        emitError(res.status === 401 || res.status === 403 ? "INVALID_KEY"
+            : res.status >= 500 || res.status === 0 ? "API_UNAVAILABLE"
+                : "CLI_ERROR", apiError(res, "Failed to create project"), "");
     }
     s.stop();
     const project = res.data;
@@ -126,12 +128,7 @@ export async function info(projectId) {
     const jsonMode = isJsonMode();
     const id = projectId || config.defaultProject;
     if (!id) {
-        const msg = "No project specified. Pass a project ID or set a default with bata projects create.";
-        if (jsonMode)
-            json({ error: msg });
-        else
-            error(msg);
-        process.exit(1);
+        emitError("NO_PROJECT", "No project specified.", "Pass a project ID or set a default with bata projects create.");
     }
     const s = jsonMode ? null : spinner("Fetching project details");
     const teamId = await resolveTeamId(token);
@@ -141,11 +138,10 @@ export async function info(projectId) {
     const res = await api.get(`/v1/projects/${id}`, token, query);
     if (!res.ok) {
         s?.stop();
-        if (jsonMode)
-            json({ error: apiError(res, "Project not found") });
-        else
-            error(apiError(res, "Project not found"));
-        process.exit(1);
+        emitError(res.status === 404 ? "NOT_FOUND"
+            : res.status === 401 || res.status === 403 ? "INVALID_KEY"
+                : res.status >= 500 || res.status === 0 ? "API_UNAVAILABLE"
+                    : "CLI_ERROR", apiError(res, "Project not found"), "");
     }
     // Also fetch connection info
     const connRes = await api.get(`/v1/connection-info/${id}`, token);
@@ -204,36 +200,44 @@ export async function info(projectId) {
     log();
 }
 export async function deleteProject(projectId) {
+    const jsonMode = isJsonMode();
     const token = requireToken();
     const config = loadConfig();
     const id = projectId || config.defaultProject;
     if (!id) {
-        error("No project specified.");
-        process.exit(1);
+        emitError("NO_PROJECT", "No project specified.", "Pass a project ID: bata projects delete <id>");
     }
-    const ok = await confirm(`Delete project ${colors.cyan(id)}? This cannot be undone.`, false);
+    // Skip the prompt headlessly (--yes / --json / no TTY) so agents and CI can
+    // actually delete — and never report success without deleting.
+    const ok = await confirmDestructive(`Delete project ${colors.cyan(id)}? This cannot be undone.`);
     if (!ok) {
         log();
         log("  Aborted.");
         log();
         return;
     }
-    const s = spinner("Deleting project");
+    const s = jsonMode ? null : spinner("Deleting project");
     const teamId = await resolveTeamId(token);
     const query = {};
     if (teamId)
         query.team_id = teamId;
     const res = await api.del(`/v1/projects/${id}`, token, query);
     if (!res.ok) {
-        s.stop();
-        error(apiError(res, "Failed to delete project"));
-        process.exit(1);
+        s?.stop();
+        emitError(res.status === 404 ? "NOT_FOUND"
+            : res.status === 401 || res.status === 403 ? "INVALID_KEY"
+                : res.status >= 500 || res.status === 0 ? "API_UNAVAILABLE"
+                    : "CLI_ERROR", apiError(res, "Failed to delete project"), "");
     }
     // Clear default project if it was this one
     if (config.defaultProject === id) {
         saveConfig({ defaultProject: undefined });
     }
-    s.stop();
+    s?.stop();
+    if (jsonMode) {
+        json({ project: { id }, deleted: true });
+        return;
+    }
     log();
     success(`Project ${id} deleted.`);
     log();
@@ -251,8 +255,6 @@ export async function handleProjects(args) {
         case undefined:
             return list();
         default:
-            error(`Unknown subcommand: projects ${sub}`);
-            log(`  ${colors.dim("Available:")} list, create, info, delete`);
-            process.exit(1);
+            emitError("INVALID_FLAG", `Unknown subcommand: projects ${sub}`, "Available: list, create, info, delete");
     }
 }

package/dist/commands/schema.js

@@ -1,37 +1,202 @@
-import { colors, log, heading } from "../utils/logger.js";
-function comingSoon(cmd) {
-    heading(`Schema: ${cmd}`);
-    log(`  ${colors.yellow("!")} ${colors.dim("Coming soon.")} Schema ${cmd} is not yet implemented.`);
+import { readFileSync } from "node:fs";
+import { api, apiError } from "../api.js";
+import { requireToken, loadConfig, isJsonMode } from "../config.js";
+import { colors, log, json, spinner, table, heading } 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.";
+/**
+ * Unimplemented schema subcommand. Never exits 0 for a no-op: emits the
+ * NOT_IMPLEMENTED envelope (exit 3) pointing at the capability that exists.
+ */
+function notImplemented(cmd) {
+    emitError("NOT_IMPLEMENTED", `Schema ${cmd} is not yet implemented.`, NOT_IMPLEMENTED_HINT);
+}
+async function readStdin() {
+    const chunks = [];
+    for await (const chunk of process.stdin)
+        chunks.push(chunk);
+    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").
+ */
+function parseCheckArgs(args) {
+    const out = { stdin: false, window: "24h" };
+    for (let i = 0; i < args.length; i++) {
+        const a = args[i];
+        if (a === "--branch") {
+            out.branch = args[++i];
+            continue;
+        }
+        if (a === "--window") {
+            out.window = args[++i] ?? out.window;
+            continue;
+        }
+        if (a === "--fail-on") {
+            out.failOn = args[++i];
+            continue;
+        }
+        if (a === "-") {
+            out.stdin = true;
+            continue;
+        }
+        if (a.startsWith("-"))
+            continue; // unknown/global flag already handled upstream
+        if (out.file === undefined)
+            out.file = a;
+    }
+    return out;
+}
+const riskColor = (r) => r === "breaking" ? colors.red(r.toUpperCase())
+    : r === "risky" || r === "unknown" ? colors.yellow(r.toUpperCase())
+        : colors.green(r.toUpperCase());
+function affectedLabel(a) {
+    if (a.index)
+        return `index ${a.index}`;
+    if (a.constraint)
+        return `constraint ${a.constraint}`;
+    if (a.table && a.columns.length)
+        return `${a.table}.${a.columns.join(", ")}`;
+    if (a.table)
+        return a.table;
+    return "—";
+}
+async function schemaCheck(args) {
+    const jsonMode = isJsonMode();
+    const { file, stdin, branch: branchId, window: timeRange, failOn } = 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.");
+    }
+    // ── read DDL (file path, explicit "-", or piped stdin) ──
+    let ddl;
+    try {
+        if (file) {
+            ddl = readFileSync(file, "utf8");
+        }
+        else if (stdin || !process.stdin.isTTY) {
+            ddl = await readStdin();
+        }
+        else {
+            emitError("EMPTY_INPUT", "No DDL provided.", 'Usage: bata schema check <file.sql>  (or pipe SQL: echo "ALTER TABLE ..." | bata schema check -)');
+        }
+    }
+    catch {
+        emitError("FILE_NOT_FOUND", `Could not read DDL from "${file}".`, "Pass a readable .sql file path or pipe SQL on stdin.");
+    }
+    if (!ddl.trim()) {
+        emitError("EMPTY_INPUT", "DDL input was empty.", "Provide a schema change to check, e.g. ALTER TABLE orders DROP COLUMN status;");
+    }
+    const token = requireToken();
+    const config = loadConfig();
+    const projectId = config.defaultProject;
+    if (!projectId) {
+        emitError("NO_PROJECT", "No default project set.", "Set one with: bata projects info <id>");
+    }
+    const body = { sql: ddl, timeRange };
+    if (branchId)
+        body.branch_id = branchId;
+    const s = jsonMode ? null : spinner("Checking schema change against live query corpus");
+    const res = await api.post(`/v1/insights/${projectId}/schema-check`, body, token);
+    s?.stop();
+    if (!res.ok) {
+        const code = res.status === 401 || res.status === 403 ? "INVALID_KEY"
+            : res.status === 404 ? "NO_PROJECT"
+                : res.status >= 500 || res.status === 0 ? "API_UNAVAILABLE"
+                    : "CLI_ERROR";
+        emitError(code, apiError(res, "Schema check failed"), "");
+    }
+    const v = res.data;
+    if (jsonMode) {
+        json(v); // server is the single source of truth for the verdict shape
+    }
+    else {
+        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"))
+        process.exit(2);
+    if (failOn === "risky" && v.overallRisk !== "safe")
+        process.exit(2);
+}
+function renderReport(v) {
+    heading("Schema check");
+    if (v.corpus.empty) {
+        log(`  ${colors.yellow("!")} No user query traffic in the last ${v.corpus.windowHours}h — cannot assert safety.`);
+    }
+    else {
+        const br = v.corpus.branchId ? ` on branch ${colors.cyan(v.corpus.branchId)}` : "";
+        log(`  ${colors.dim(`Checked against ${v.corpus.queryShapes} query shapes (${v.corpus.totalCalls.toLocaleString()} calls) over ${v.corpus.windowHours}h${br}`)}`);
+    }
     log();
-    log(`  ${colors.dim("Track progress at")} ${colors.cyan("https://github.com/zvndev")}`);
+    log(`  Verdict: ${riskColor(v.overallRisk)}   ${colors.dim(`${v.summary.breakingCount} breaking · ${v.summary.riskyCount} risky · ${v.summary.safeCount} safe · ${v.summary.unknownCount} unknown`)}`);
+    if (v.summary.totalCallsAtRisk > 0) {
+        log(`  ${colors.red(`${v.summary.totalCallsAtRisk.toLocaleString()} calls/window hit a breaking change`)}`);
+    }
+    log();
+    for (const f of v.findings) {
+        log(`  ${riskColor(f.risk)}  ${colors.bold(f.operation)}  ${colors.dim(affectedLabel(f.affected))}`);
+        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,
+                q.calls.toLocaleString(),
+                `${q.meanTimeMs}ms`,
+                q.risk,
+            ]));
+            if (f.impactedQueries.length > shown.length) {
+                log(`    ${colors.dim(`+ ${f.impactedQueries.length - shown.length} more`)}`);
+            }
+        }
+        if (f.note)
+            log(`    ${colors.yellow("note:")} ${colors.dim(f.note)}`);
+        if (f.suggestion)
+            log(`    ${colors.cyan("fix:")} ${colors.dim(f.suggestion)}`);
+        log();
+    }
+    for (const n of v.notes)
+        log(`  ${colors.dim(`· ${n}`)}`);
     log();
 }
 export async function handleSchema(args) {
     const sub = args[0];
     switch (sub) {
+        case "check":
+            return schemaCheck(args.slice(1));
         case "init":
-            comingSoon("init");
-            break;
+            notImplemented("init");
         case "push":
-            comingSoon("push");
-            break;
+            notImplemented("push");
         case "pull":
-            comingSoon("pull");
-            break;
+            notImplemented("pull");
         case "diff":
-            comingSoon("diff");
-            break;
+            notImplemented("diff");
         default:
             log();
-            log(`  ${colors.bold("bata schema")} ${colors.dim("— Turbine ORM schema management")}`);
+            log(`  ${colors.bold("bata schema")} ${colors.dim("— schema safety & management")}`);
             log();
             log(`  ${colors.dim("Commands:")}`);
-            log(`    ${colors.cyan("init")}    Initialize schema from existing database`);
-            log(`    ${colors.cyan("push")}    Push schema changes to database`);
-            log(`    ${colors.cyan("pull")}    Pull schema from database`);
-            log(`    ${colors.cyan("diff")}    Show pending schema changes`);
+            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();
+            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("--fail-on <breaking|risky>  exit 2 to gate CI (fail-closed: 'unknown' also trips)")}`);
             log();
-            log(`  ${colors.yellow("!")} ${colors.dim("All schema commands are coming soon.")}`);
+            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 check migration.sql --fail-on breaking   # CI gate")}`);
             log();
     }
 }

package/dist/commands/status.js

@@ -4,9 +4,10 @@
  * Lists projects with branch count, compute status, and storage size.
  * Colorized output: green for running, yellow for suspended, red for error.
  */
-import { api, apiError } from "../api.js";
+import { api, apiError, resolveTeamId } from "../api.js";
 import { requireToken, loadConfig, isJsonMode } from "../config.js";
-import { colors, log, json, error, spinner, table, heading } from "../utils/logger.js";
+import { colors, log, json, spinner, table, heading } from "../utils/logger.js";
+import { emitError } from "../utils/errors.js";
 function statusBadge(status) {
     switch (status?.toLowerCase()) {
         case "active":
@@ -36,19 +37,21 @@ export async function status() {
     const config = loadConfig();
     const jsonMode = isJsonMode();
     const s = jsonMode ? null : spinner("Fetching projects");
-    const query = {};
-    if (config.defaultTeam)
-        query.team_id = config.defaultTeam;
-    const res = await api.get("/v1/projects", token, query);
+    // GET /v1/projects requires a team_id. On the API-key path config.defaultTeam
+    // is empty, so resolve it the way `create` does (falls back to the user's
+    // first team) — otherwise this 400s headlessly.
+    const teamId = await resolveTeamId(token);
+    if (!teamId) {
+        s?.stop();
+        emitError("NO_TEAM", "No team found for this credential.", "This API key isn't attached to a team. Run `bata login` or check `bata whoami`.");
+    }
+    const res = await api.get("/v1/projects", token, { team_id: teamId });
     if (!res.ok) {
         s?.stop();
-        if (jsonMode) {
-            json({ error: apiError(res, "Failed to fetch projects") });
-        }
-        else {
-            error(apiError(res, "Failed to fetch projects"));
-        }
-        process.exit(1);
+        // Surface the server's validation message, not a bare "HTTP 400".
+        emitError(res.status === 401 || res.status === 403 ? "INVALID_KEY"
+            : res.status >= 500 || res.status === 0 ? "API_UNAVAILABLE"
+                : "CLI_ERROR", apiError(res, "Failed to fetch projects"), "");
     }
     s?.stop();
     const projects = Array.isArray(res.data) ? res.data : [];

package/dist/commands/usage.d.ts

@@ -0,0 +1,13 @@
+/**
+ * bata usage — Cost truth for the current billing period.
+ *
+ * Calls the control-plane current-usage endpoint (GET /v1/billing/current-usage)
+ * and renders per-dimension cost for the credential's team.
+ *
+ * HONESTY RULE (the whole point of the cost-truth wedge):
+ *   A dimension that is NOT actually metered must render "Not metered yet" and
+ *   NEVER a priced $0. Today transfer is not metered end-to-end, so it reports
+ *   { metered: false, value: null, cost_cents: null, status: "not_metered_yet" }.
+ *   We will only show a dollar figure for a dimension we genuinely meter.
+ */
+export declare function usage(args: string[]): Promise<void>;

package/dist/commands/usage.js

@@ -0,0 +1,164 @@
+/**
+ * bata usage — Cost truth for the current billing period.
+ *
+ * Calls the control-plane current-usage endpoint (GET /v1/billing/current-usage)
+ * and renders per-dimension cost for the credential's team.
+ *
+ * HONESTY RULE (the whole point of the cost-truth wedge):
+ *   A dimension that is NOT actually metered must render "Not metered yet" and
+ *   NEVER a priced $0. Today transfer is not metered end-to-end, so it reports
+ *   { metered: false, value: null, cost_cents: null, status: "not_metered_yet" }.
+ *   We will only show a dollar figure for a dimension we genuinely meter.
+ */
+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";
+/**
+ * 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
+ * treated as not-metered for transfer (the API doesn't meter it yet); compute
+ * and storage default to metered because those ARE wired up end-to-end.
+ */
+function dimensionView(dim, value, unit, meteredDefault) {
+    const metered = dim?.metered ?? meteredDefault;
+    if (!metered) {
+        return { metered: false, value: null, unit, cost_cents: null, status: "not_metered_yet" };
+    }
+    return {
+        metered: true,
+        value,
+        unit,
+        cost_cents: dim?.costCents ?? null,
+        status: "metered",
+    };
+}
+function dollars(cents) {
+    if (cents === null)
+        return colors.dim("Not metered yet");
+    return `$${(cents / 100).toFixed(cents % 100 === 0 ? 2 : 4)}`;
+}
+function valueLabel(d) {
+    if (!d.metered || d.value === null)
+        return colors.dim("—");
+    return `${d.value} ${d.unit}`;
+}
+function parseProjectFlag(args) {
+    for (let i = 0; i < args.length; i++) {
+        if (args[i] === "--project" && args[i + 1])
+            return args[i + 1];
+        if (args[i].startsWith("--project="))
+            return args[i].slice("--project=".length);
+    }
+    return undefined;
+}
+export async function usage(args) {
+    const jsonMode = isJsonMode();
+    const token = requireToken();
+    const projectFilter = parseProjectFlag(args);
+    const s = jsonMode ? null : spinner("Fetching usage");
+    // current-usage derives the team from the credential — no team_id needed.
+    const res = await api.get("/v1/billing/current-usage", token);
+    s?.stop();
+    if (!res.ok) {
+        emitError(res.status === 401 || res.status === 403 ? "INVALID_KEY"
+            : res.status >= 500 || res.status === 0 ? "API_UNAVAILABLE"
+                : "CLI_ERROR", apiError(res, "Failed to fetch usage"), "");
+    }
+    const data = res.data ?? {};
+    let projects = data.projects ?? [];
+    if (projectFilter) {
+        projects = projects.filter((p) => p.projectId === projectFilter || p.projectName === projectFilter);
+        if (projects.length === 0) {
+            emitError("NOT_FOUND", `No usage for project "${projectFilter}".`, "Check the project id/name with: bata projects list --json");
+        }
+    }
+    // Build per-project, per-dimension views. compute + storage are metered;
+    // transfer is NOT metered end-to-end yet → "Not metered yet", never $0.
+    const projectViews = projects.map((p) => {
+        const compute = dimensionView(p.compute, p.compute?.hours ?? null, "CU-hr", true);
+        const storage = dimensionView(p.storage, p.storage?.gb ?? null, "GB", true);
+        const transfer = dimensionView(p.transfer, p.transfer?.gb ?? null, "GB", false);
+        return { project: p, compute, storage, transfer };
+    });
+    // Recommendations: top-level + any per-project ones, normalized with an action.
+    const recommendations = [
+        ...(data.recommendations ?? []),
+        ...projects
+            .filter((p) => p.recommendation)
+            .map((p) => ({ ...p.recommendation, projectId: p.projectId })),
+    ]
+        .filter((r) => r && (r.message || r.action))
+        .map((r) => ({
+        kind: r.kind ?? "suspend_idle",
+        message: r.message ?? "",
+        action: r.action ?? null,
+    }));
+    if (jsonMode) {
+        json({
+            period_start: data.periodStart ?? null,
+            plan: data.plan ?? null,
+            pricing: data.pricing ?? null,
+            projects: projectViews.map(({ project, compute, storage, transfer }) => ({
+                project_id: project.projectId,
+                project_name: project.projectName,
+                status: project.status ?? null,
+                // Honest envelope: metered dimensions carry a number, un-metered ones
+                // carry nulls and status:"not_metered_yet" — never a priced $0.
+                compute,
+                storage,
+                transfer,
+                active_computes: project.activeComputes?.length ?? 0,
+            })),
+            totals: data.totals
+                ? {
+                    estimated_cost_cents: data.totals.estimatedCostCents ?? 0,
+                    compute_hours: data.totals.computeHours ?? null,
+                    storage_gb: data.totals.storageGb ?? null,
+                    // transfer is not metered yet → null + status, not 0
+                    transfer: { metered: false, value: null, unit: "GB", cost_cents: null, status: "not_metered_yet" },
+                    active_computes: data.totals.activeComputes ?? 0,
+                }
+                : null,
+            recommendations,
+        });
+        return;
+    }
+    // ── Human output ──
+    heading("Usage — current period");
+    const planName = data.plan?.name ?? "free";
+    const base = data.plan?.monthlyBaseCents ?? 0;
+    kvList([
+        ["Plan", `${planName}${base ? ` (${dollars(base)}/mo base)` : ""}`],
+        ["Period start", data.periodStart ? new Date(data.periodStart).toLocaleDateString("en-US", { month: "short", day: "numeric", year: "numeric" }) : "-"],
+    ]);
+    log();
+    if (projectViews.length === 0) {
+        log(`  ${colors.dim("No projects with usage in this period.")}`);
+        log();
+        return;
+    }
+    for (const { project, compute, storage, transfer } of projectViews) {
+        log(`  ${colors.bold(project.projectName)} ${colors.dim(project.projectId)}`);
+        table(["DIMENSION", "USAGE", "COST"], [
+            ["Compute", valueLabel(compute), dollars(compute.cost_cents)],
+            ["Storage", valueLabel(storage), dollars(storage.cost_cents)],
+            ["Transfer", valueLabel(transfer), dollars(transfer.cost_cents)],
+        ]);
+        log();
+    }
+    if (data.totals) {
+        const total = data.totals.estimatedCostCents ?? 0;
+        log(`  ${colors.bold("Total estimated:")} ${dollars(total + base)}  ${colors.dim("(metered dimensions only — transfer not metered yet)")}`);
+        log();
+    }
+    if (recommendations.length) {
+        log(`  ${colors.bold("Recommendations")}`);
+        for (const r of recommendations) {
+            log(`    ${colors.yellow("·")} ${r.message}`);
+            if (r.action)
+                log(`      ${colors.cyan(r.action)}`);
+        }
+        log();
+    }
+}