@batadata/cli 0.1.1 → 0.1.3

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();
+    }
+}

package/dist/config.d.ts

@@ -13,9 +13,12 @@ interface RuntimeContext {
     apiKey?: string;
     apiUrl?: string;
     json: boolean;
+    yes: boolean;
 }
 export declare function setRuntime(ctx: Partial<RuntimeContext>): void;
 export declare function isJsonMode(): boolean;
+/** Was `--yes` / `-y` passed? (Skips destructive confirmation prompts.) */
+export declare function isYes(): boolean;
 export declare function loadConfig(): BataConfig;
 export declare function saveConfig(config: Partial<BataConfig>): void;
 export declare function clearConfig(): void;

package/dist/config.js

@@ -3,7 +3,7 @@ import * as path from "node:path";
 import * as os from "node:os";
 const CONFIG_PATH = path.join(os.homedir(), ".batarc");
 const DEFAULT_API_URL = "https://api.batadata.com";
-const runtime = { json: false };
+const runtime = { json: false, yes: false };
 export function setRuntime(ctx) {
     if (ctx.apiKey !== undefined)
         runtime.apiKey = ctx.apiKey;
@@ -11,10 +11,16 @@ export function setRuntime(ctx) {
         runtime.apiUrl = ctx.apiUrl;
     if (ctx.json !== undefined)
         runtime.json = ctx.json;
+    if (ctx.yes !== undefined)
+        runtime.yes = ctx.yes;
 }
 export function isJsonMode() {
     return runtime.json;
 }
+/** Was `--yes` / `-y` passed? (Skips destructive confirmation prompts.) */
+export function isYes() {
+    return runtime.yes;
+}
 export function loadConfig() {
     try {
         const raw = fs.readFileSync(CONFIG_PATH, "utf-8");
@@ -70,7 +76,8 @@ export function requireToken() {
                 "\x1b[36m--api-key\x1b[0m, set \x1b[36mBATA_API_KEY\x1b[0m, or run " +
                 "\x1b[36mbata login\x1b[0m.");
         }
-        process.exit(1);
+        // Exit 4 = auth/credentials per the documented exit-code contract.
+        process.exit(4);
     }
     return token;
 }

package/dist/index.js

@@ -10,10 +10,12 @@ import { dev } from "./commands/dev.js";
 import { create } from "./commands/create.js";
 import { status } from "./commands/status.js";
 import { connect } from "./commands/connect.js";
+import { usage } from "./commands/usage.js";
 import { parseGlobalFlags } from "./args.js";
 import { isJsonMode } from "./config.js";
 import { colors, log, banner } from "./utils/logger.js";
-const VERSION = "0.1.1";
+import { exitCodeFor, isRetryable } from "./utils/errors.js";
+const VERSION = "0.1.3";
 function help() {
     banner();
     log(`  ${colors.bold("Usage")}`);
@@ -23,6 +25,7 @@ function help() {
     log(`    ${colors.cyan("create <name>")}     Create a project and wait for it to be ready`);
     log(`    ${colors.cyan("connect <name>")}    Open psql to a project (auto-wakes if suspended)`);
     log(`    ${colors.cyan("status")}             Show all projects and their status`);
+    log(`    ${colors.cyan("usage")}              Per-dimension cost for the current period`);
     log();
     log(`  ${colors.bold("Auth")}`);
     log(`    ${colors.cyan("login")}              Log in to BataDB`);
@@ -40,11 +43,11 @@ function help() {
     log(`  ${colors.bold("Database")}`);
     log(`    ${colors.cyan("db connect")}         Open psql to your database`);
     log(`    ${colors.cyan("db url")}             Print connection string`);
-    log(`    ${colors.cyan("db branches")}        List database branches`);
+    log(`    ${colors.cyan("db branches")}        List database branches ${colors.dim("(STATUS shows compute readiness)")}`);
     log(`    ${colors.cyan("db branch create")}   Create a new branch`);
     log(`    ${colors.cyan("db branch delete")}   Delete a branch`);
     log(`    ${colors.cyan("db studio")}          Open table browser in browser`);
-    log(`    ${colors.cyan("db query")}           Run a SQL query`);
+    log(`    ${colors.cyan("db query")}           Run a SQL query ${colors.dim("(--branch <id> to target a branch)")}`);
     log();
     log(`  ${colors.bold("Schema & Types")}`);
     log(`    ${colors.cyan("generate")}           Generate types from database schema`);
@@ -63,9 +66,25 @@ function help() {
     log(`    ${colors.dim("--help, -h")}         Show this help message`);
     log(`    ${colors.dim("--version, -v")}      Show version`);
     log();
-    log(`  ${colors.bold("Headless / agents")}`);
+    log(`  ${colors.bold("Agents")} ${colors.dim("(headless, machine-readable)")}`);
     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")}${colors.dim(".")}`);
+    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("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();
+    log(`    ${colors.dim("All errors in --json mode share one envelope:")} ${colors.dim('{ "error", "code", "hint" }')} ${colors.dim("on stderr.")}`);
+    log();
+    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("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)")}`);
+    log(`    ${colors.dim("6")}  upstream / transient ${colors.dim("(API_UNAVAILABLE, TIMEOUT, COMPUTE_STARTING — retryable)")}`);
     log();
     log(`  ${colors.dim("Documentation:")} ${colors.cyan("https://www.npmjs.com/package/@batadata/cli")}`);
     log();
@@ -99,6 +118,9 @@ async function main() {
             case "connect":
                 await connect(rest);
                 break;
+            case "usage":
+                await usage(rest);
+                break;
             // Auth
             case "login":
                 await login();
@@ -144,25 +166,42 @@ async function main() {
                 await dev();
                 break;
             default:
-                log();
-                log(`  ${colors.red("Error:")} Unknown command ${colors.white(command)}`);
-                log();
-                log(`  Run ${colors.cyan("bata --help")} to see available commands.`);
-                log();
-                process.exit(1);
+                if (isJsonMode()) {
+                    log(JSON.stringify({
+                        error: `Unknown command "${command}".`,
+                        code: "INVALID_FLAG",
+                        hint: "Run `bata --help` to see available commands.",
+                    }, null, 2));
+                }
+                else {
+                    log();
+                    log(`  ${colors.red("Error:")} Unknown command ${colors.white(command)}`);
+                    log();
+                    log(`  Run ${colors.cyan("bata --help")} to see available commands.`);
+                    log();
+                }
+                process.exit(exitCodeFor("INVALID_FLAG"));
         }
     }
     catch (err) {
         const message = err instanceof Error ? err.message : String(err);
+        // Network/transport throws (e.g. the request timed out, DNS/connection
+        // refused) are upstream/transient — surface them with a retryable code so
+        // agents know to back off rather than treating it as a hard CLI bug.
+        const timedOut = /timed out/i.test(message);
+        const transient = timedOut
+            || /ENOTFOUND|ECONNRESET|EAI_AGAIN|socket hang up/i.test(message)
+            || isRetryable({ message });
+        const code = transient ? (timedOut ? "TIMEOUT" : "API_UNAVAILABLE") : "CLI_ERROR";
         if (isJsonMode()) {
-            log(JSON.stringify({ error: message, code: "CLI_ERROR" }, null, 2));
+            log(JSON.stringify({ error: message, code, hint: "" }, null, 2));
         }
         else {
             log();
             log(`  ${colors.red("Error:")} ${message}`);
             log();
         }
-        process.exit(1);
+        process.exit(exitCodeFor(code));
     }
 }
 main();

package/dist/utils/errors.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Shared error / exit-code contract for the whole CLI.
+ *
+ * Every command emits ONE JSON error envelope in --json mode:
+ *   { "error": string, "code": SCREAMING_SNAKE, "hint": string }
+ * Errors always go to stderr (via error()); the envelope is the only thing on
+ * stdout in --json mode, so machine consumers can parse stdout cleanly.
+ *
+ * ── Exit-code contract (documented + surfaced in `bata --help`) ──
+ *   0  success
+ *   1  generic CLI_ERROR (genuinely-unknown failure)
+ *   2  gate tripped (schema check --fail-on)
+ *   3  NOT_IMPLEMENTED (coming-soon command — never a silent no-op exit 0)
+ *   4  auth / creds        — NO_CREDENTIALS, INVALID_KEY
+ *   5  not-found/bad-input — NO_PROJECT, BRANCH_NOT_FOUND, INVALID_FLAG, INTERACTIVE_ONLY, ...
+ *   6  upstream/transient  — API_UNAVAILABLE, TIMEOUT, COMPUTE_STARTING (retryable)
+ */
+export type ErrorCode = "CLI_ERROR" | "NOT_IMPLEMENTED" | "NO_CREDENTIALS" | "INVALID_KEY" | "NO_PROJECT" | "BRANCH_NOT_FOUND" | "INVALID_FLAG" | "INTERACTIVE_ONLY" | "NO_TEAM" | "EMPTY_INPUT" | "FILE_NOT_FOUND" | "MISSING_ARG" | "NOT_FOUND" | "API_UNAVAILABLE" | "TIMEOUT" | "COMPUTE_STARTING" | "GATE_TRIPPED";
+/**
+ * Decide whether a failed request is upstream/transient (retryable, exit 6)
+ * rather than a hard CLI error. An agent that sees exit 6 should back off and
+ * retry; exit 1 means "don't bother, it won't fix itself".
+ *
+ * Retryable signals:
+ *   - HTTP 503 (compute waking up) or 0 (no response / connection refused)
+ *   - HTTP >= 500 (any upstream blip)
+ *   - an error `code` of COMPUTE_STARTING / API_UNAVAILABLE / TIMEOUT
+ *   - a connection-refused / ECONNREFUSED transport message
+ *
+ * Genuine SQL errors (syntax, etc.) carry none of these and stay exit 1.
+ */
+export declare function isRetryable(opts: {
+    status?: number;
+    code?: string;
+    message?: string;
+}): boolean;
+/** Map an error code to its documented process exit code. */
+export declare function exitCodeFor(code: string): number;
+/**
+ * Emit the single error envelope and exit with the code that matches `code`.
+ * In --json mode: `{ error, code, hint }` to stdout-as-JSON (errors stay clean).
+ * In human mode: a red "Error:" line to stderr plus a dim hint.
+ *
+ * Promoted from schema.ts so every command shares one contract. Pass an explicit
+ * `exitCode` only to override the table (rare — e.g. forcing 1 on an unknown).
+ */
+export declare function emitError(code: ErrorCode | string, message: string, hint?: string, exitCode?: number): never;

package/dist/utils/errors.js

@@ -0,0 +1,91 @@
+/**
+ * Shared error / exit-code contract for the whole CLI.
+ *
+ * Every command emits ONE JSON error envelope in --json mode:
+ *   { "error": string, "code": SCREAMING_SNAKE, "hint": string }
+ * Errors always go to stderr (via error()); the envelope is the only thing on
+ * stdout in --json mode, so machine consumers can parse stdout cleanly.
+ *
+ * ── Exit-code contract (documented + surfaced in `bata --help`) ──
+ *   0  success
+ *   1  generic CLI_ERROR (genuinely-unknown failure)
+ *   2  gate tripped (schema check --fail-on)
+ *   3  NOT_IMPLEMENTED (coming-soon command — never a silent no-op exit 0)
+ *   4  auth / creds        — NO_CREDENTIALS, INVALID_KEY
+ *   5  not-found/bad-input — NO_PROJECT, BRANCH_NOT_FOUND, INVALID_FLAG, INTERACTIVE_ONLY, ...
+ *   6  upstream/transient  — API_UNAVAILABLE, TIMEOUT, COMPUTE_STARTING (retryable)
+ */
+import { isJsonMode } from "../config.js";
+import { colors, log, json, error } from "./logger.js";
+/**
+ * Decide whether a failed request is upstream/transient (retryable, exit 6)
+ * rather than a hard CLI error. An agent that sees exit 6 should back off and
+ * retry; exit 1 means "don't bother, it won't fix itself".
+ *
+ * Retryable signals:
+ *   - HTTP 503 (compute waking up) or 0 (no response / connection refused)
+ *   - HTTP >= 500 (any upstream blip)
+ *   - an error `code` of COMPUTE_STARTING / API_UNAVAILABLE / TIMEOUT
+ *   - a connection-refused / ECONNREFUSED transport message
+ *
+ * Genuine SQL errors (syntax, etc.) carry none of these and stay exit 1.
+ */
+export function isRetryable(opts) {
+    const { status, code, message } = opts;
+    if (status === 503 || status === 0)
+        return true;
+    if (typeof status === "number" && status >= 500)
+        return true;
+    if (code === "COMPUTE_STARTING" || code === "API_UNAVAILABLE" || code === "TIMEOUT")
+        return true;
+    if (message && /ECONNREFUSED|connection refused/i.test(message))
+        return true;
+    return false;
+}
+/** Map an error code to its documented process exit code. */
+export function exitCodeFor(code) {
+    switch (code) {
+        case "NOT_IMPLEMENTED":
+            return 3;
+        case "NO_CREDENTIALS":
+        case "INVALID_KEY":
+            return 4;
+        case "NO_PROJECT":
+        case "BRANCH_NOT_FOUND":
+        case "INVALID_FLAG":
+        case "INTERACTIVE_ONLY":
+        case "NO_TEAM":
+        case "EMPTY_INPUT":
+        case "FILE_NOT_FOUND":
+        case "MISSING_ARG":
+        case "NOT_FOUND":
+            return 5;
+        case "API_UNAVAILABLE":
+        case "TIMEOUT":
+        case "COMPUTE_STARTING":
+            return 6;
+        case "GATE_TRIPPED":
+            return 2;
+        default:
+            return 1; // CLI_ERROR / unknown
+    }
+}
+/**
+ * Emit the single error envelope and exit with the code that matches `code`.
+ * In --json mode: `{ error, code, hint }` to stdout-as-JSON (errors stay clean).
+ * In human mode: a red "Error:" line to stderr plus a dim hint.
+ *
+ * Promoted from schema.ts so every command shares one contract. Pass an explicit
+ * `exitCode` only to override the table (rare — e.g. forcing 1 on an unknown).
+ */
+export function emitError(code, message, hint = "", exitCode) {
+    if (isJsonMode()) {
+        json({ error: message, code, hint });
+    }
+    else {
+        error(message);
+        if (hint)
+            log(`  ${colors.dim(hint)}`);
+    }
+    process.exit(exitCode ?? exitCodeFor(code));
+}

package/dist/utils/logger.js

@@ -124,6 +124,6 @@ export function kvList(items) {
 // Banner
 export function banner() {
     log();
-    log(`  ${colors.cyan(colors.bold("BataDB"))} ${colors.dim("v0.1.0")} ${colors.dim("— serverless Postgres platform")}`);
+    log(`  ${colors.cyan(colors.bold("BataDB"))} ${colors.dim("v0.1.3")} ${colors.dim("— serverless Postgres platform")}`);
     log();
 }

package/dist/utils/prompts.d.ts

@@ -1,6 +1,16 @@
 export declare function prompt(message: string, defaultValue?: string): Promise<string>;
 export declare function promptSecret(message: string): Promise<string>;
 export declare function confirm(message: string, defaultYes?: boolean): Promise<boolean>;
+/**
+ * Confirmation for a destructive action that MUST proceed unattended.
+ *
+ * Returns true (proceed) without prompting whenever the caller can't answer:
+ *   --yes / -y  ·  --json mode  ·  no TTY (piped / agent / CI).
+ * This is the one place the headless-skip rule lives so it can't drift between
+ * `db branch delete`, `projects delete`, and `api-keys revoke`. In an
+ * interactive TTY it asks `message` and defaults to NO.
+ */
+export declare function confirmDestructive(message: string): Promise<boolean>;
 export declare function select(message: string, options: {
     label: string;
     value: string;

package/dist/utils/prompts.js

@@ -1,5 +1,6 @@
 import * as readline from "node:readline";
 import { colors, log } from "./logger.js";
+import { isJsonMode, isYes } from "../config.js";
 function createInterface() {
     return readline.createInterface({
         input: process.stdin,
@@ -74,6 +75,20 @@ export async function confirm(message, defaultYes = true) {
         return defaultYes;
     return answer.toLowerCase().startsWith("y");
 }
+/**
+ * Confirmation for a destructive action that MUST proceed unattended.
+ *
+ * Returns true (proceed) without prompting whenever the caller can't answer:
+ *   --yes / -y  ·  --json mode  ·  no TTY (piped / agent / CI).
+ * This is the one place the headless-skip rule lives so it can't drift between
+ * `db branch delete`, `projects delete`, and `api-keys revoke`. In an
+ * interactive TTY it asks `message` and defaults to NO.
+ */
+export async function confirmDestructive(message) {
+    if (isYes() || isJsonMode() || !process.stdin.isTTY)
+        return true;
+    return confirm(message, false);
+}
 export async function select(message, options) {
     log(`  ${colors.cyan("?")} ${message}`);
     log();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@batadata/cli",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "CLI for BataDB — serverless Postgres platform",
   "bin": {
     "bata": "./dist/index.js"
@@ -8,15 +8,16 @@
   "type": "module",
   "scripts": {
     "build": "tsc",
-    "dev": "tsc --watch"
+    "dev": "tsc --watch",
+    "test": "vitest run"
   },
   "engines": {
     "node": ">=20.0.0"
   },
-  "dependencies": {},
   "devDependencies": {
+    "@types/node": "^22.10.0",
     "typescript": "^5.7.0",
-    "@types/node": "^22.10.0"
+    "vitest": "^3.2.6"
   },
   "files": [
     "dist"