@batadata/cli 0.1.1 → 0.1.2

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 } from "./utils/errors.js";
+const VERSION = "0.1.2";
 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`);
@@ -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 — 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,39 @@ 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 transient = /timed out|ECONNREFUSED|ENOTFOUND|ECONNRESET|EAI_AGAIN|socket hang up/i.test(message);
+        const code = transient ? (/timed out/i.test(message) ? "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,29 @@
+/**
+ * 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 (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" | "GATE_TRIPPED";
+/** 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,65 @@
+/**
+ * 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 (retryable)
+ */
+import { isJsonMode } from "../config.js";
+import { colors, log, json, error } from "./logger.js";
+/** 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":
+            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.2")} ${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.2",
   "description": "CLI for BataDB — serverless Postgres platform",
   "bin": {
     "bata": "./dist/index.js"