@batadata/cli 0.1.2 → 0.1.3

package/dist/api.js

@@ -14,7 +14,7 @@ export async function request(method, path, options = {}) {
     }
     const headers = {
         "Content-Type": "application/json",
-        "User-Agent": "@batadata/cli 0.1.2",
+        "User-Agent": "@batadata/cli 0.1.3",
     };
     if (options.token) {
         headers["Authorization"] = `Bearer ${options.token}`;

package/dist/commands/db.d.ts

@@ -4,5 +4,5 @@ export declare function branches(): Promise<void>;
 export declare function branchCreate(name?: string): Promise<void>;
 export declare function branchDelete(name?: string): Promise<void>;
 export declare function studio(): Promise<void>;
-export declare function query(sql?: string): Promise<void>;
+export declare function query(args?: string[]): Promise<void>;
 export declare function handleDb(args: string[]): Promise<void>;

package/dist/commands/db.js

@@ -4,7 +4,7 @@ import { requireToken, loadConfig, isJsonMode } from "../config.js";
 import { colors, log, json, error, spinner, table, heading, info as logInfo } from "../utils/logger.js";
 import { prompt, confirmDestructive } from "../utils/prompts.js";
 import { openBrowser } from "../utils/open.js";
-import { emitError } from "../utils/errors.js";
+import { emitError, isRetryable } from "../utils/errors.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" });
@@ -30,6 +30,17 @@ function formatDate(iso) {
     const d = new Date(iso);
     return d.toLocaleDateString("en-US", { month: "short", day: "numeric", year: "numeric" });
 }
+/**
+ * Human-readable STATUS cell for a branch. Prefers the live compute lifecycle
+ * (computeStatus) over the static branch row status, and appends a green check
+ * when the compute is ready to serve a query without a cold start.
+ */
+function branchStatusLabel(b) {
+    const base = b.computeStatus || b.status || "-";
+    if (b.ready === true)
+        return `${base} ${colors.green("✓")}`;
+    return base;
+}
 /**
  * Resolve a project's primary branch (the one to run a query against). Lists
  * branches the same way `db branches` does (GET /v1/projects/:id) and returns
@@ -133,6 +144,10 @@ export async function branches() {
                 name: b.name,
                 is_primary: b.is_primary,
                 status: b.status,
+                // Compute readiness — what agents poll on between a create/cold start
+                // and a successful query.
+                computeStatus: b.computeStatus ?? null,
+                ready: b.ready ?? null,
                 created_at: b.created_at,
             })),
             count: branchList.length,
@@ -148,7 +163,9 @@ export async function branches() {
     table(["NAME", "PRIMARY", "STATUS", "CREATED"], branchList.map((b) => [
         b.name,
         b.is_primary ? colors.green("yes") : "-",
-        b.status || "-",
+        // Prefer the live compute lifecycle (computeStatus); fall back to the
+        // branch row status. Mark ready with a check so the column is scannable.
+        branchStatusLabel(b),
         formatDate(b.created_at),
     ]));
     log();
@@ -257,8 +274,33 @@ export async function studio() {
     log();
     openBrowser(studioUrl);
 }
-export async function query(sql) {
+/**
+ * Pull a `--branch <id>` / `--branch=<id>` flag out of the query args and return
+ * the explicit branch id (if any) 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.
+ */
+function parseBranchFlag(args) {
+    let branchId;
+    const rest = [];
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i];
+        if (arg === "--branch") {
+            branchId = args[++i];
+        }
+        else if (arg.startsWith("--branch=")) {
+            branchId = arg.slice("--branch=".length);
+        }
+        else {
+            rest.push(arg);
+        }
+    }
+    return { branchId, rest };
+}
+export async function query(args = []) {
     const jsonMode = isJsonMode();
+    const { branchId, rest } = parseBranchFlag(args);
+    const sql = rest.join(" ").trim();
     if (!sql) {
         emitError("MISSING_ARG", "SQL query is required.", 'Usage: bata db query "SELECT 1"');
     }
@@ -269,19 +311,30 @@ export async function query(sql) {
         emitError("NO_PROJECT", "No default project set.", "Set one with: bata projects info <id>");
     }
     const s = jsonMode ? null : spinner("Running query");
-    // Resolve the primary branch — /v1/sql/execute is keyed on branch_id, not
+    // Target branch: an explicit --branch <id> wins; otherwise resolve the
+    // project's primary branch. /v1/sql/execute is keyed on branch_id, not
     // project. (The old code POSTed to /v1/query/:projectId, which 404s.)
-    const branch = await getPrimaryBranch(projectId, token, config.defaultTeam);
-    if (!branch) {
-        s?.stop();
-        emitError("BRANCH_NOT_FOUND", "No branch found for this project to run the query against.", "Check the project with: bata db branches --json");
+    let branchId_ = branchId;
+    if (!branchId_) {
+        const branch = await getPrimaryBranch(projectId, token, config.defaultTeam);
+        if (!branch) {
+            s?.stop();
+            emitError("BRANCH_NOT_FOUND", "No branch found for this project to run the query against.", "Check the project with: bata db branches --json");
+        }
+        branchId_ = branch.id;
     }
-    const res = await api.post("/v1/sql/execute", { branch_id: branch.id, query: sql }, token);
+    const res = await api.post("/v1/sql/execute", { branch_id: branchId_, query: sql }, token);
     s?.stop();
     if (!res.ok) {
-        const code = res.status === 401 || res.status === 403 ? "INVALID_KEY"
-            : res.status >= 500 || res.status === 0 ? "API_UNAVAILABLE"
-                : "CLI_ERROR";
+        // Cold-start / upstream blips are retryable (exit 6) so an agent backs off
+        // and retries instead of treating it as a hard CLI bug. The backend returns
+        // 503 + { code: "COMPUTE_STARTING" } while a just-created/idle branch's
+        // compute is still waking; connection-refused transients land here too.
+        const body = res.data;
+        if (isRetryable({ status: res.status, code: body?.code, message: body?.error })) {
+            emitError("COMPUTE_STARTING", apiError(res, "Compute is starting"), "compute is starting; retry in a few seconds");
+        }
+        const code = res.status === 401 || res.status === 403 ? "INVALID_KEY" : "CLI_ERROR";
         emitError(code, apiError(res, "Query failed"), "");
     }
     // The endpoint returns 200 even when the SQL itself errored (it executed and
@@ -330,8 +383,85 @@ function fmtCell(v) {
         return JSON.stringify(v);
     return String(v);
 }
+/** Was a `--help` / `-h` flag passed anywhere in the args? */
+function hasHelpFlag(args) {
+    return args.some((a) => a === "--help" || a === "-h");
+}
+/**
+ * Print usage for a `db` subcommand (or general `db` help if none/unknown) and
+ * return. Pure stdout — NEVER touches the network. `db query --help` must print
+ * this, not run the SQL "--help".
+ */
+function dbHelp(sub) {
+    const usage = (line) => log(`  ${colors.cyan(line)}`);
+    const note = (line) => log(`  ${colors.dim(line)}`);
+    log();
+    switch (sub) {
+        case "query":
+            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 <branch_id>] [--json]");
+            log();
+            note("--branch <branch_id>   Target a specific branch (default: the project's primary)");
+            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.");
+            break;
+        case "branches":
+            log(`  ${colors.bold("bata db branches")} — list branches and their compute status`);
+            log();
+            usage("bata db branches [--json]");
+            log();
+            note("STATUS shows the live compute state; a ✓ means ready to query.");
+            note("--json includes computeStatus + ready — poll these after create/cold start.");
+            break;
+        case "branch":
+            log(`  ${colors.bold("bata db branch")} — create or delete a branch`);
+            log();
+            usage("bata db branch create <name>");
+            usage("bata db branch delete <name> [--yes]");
+            break;
+        case "url":
+            log(`  ${colors.bold("bata db url")} — print the connection string`);
+            log();
+            usage("bata db url [--json]");
+            break;
+        case "connect":
+            log(`  ${colors.bold("bata db connect")} — open an interactive psql session`);
+            log();
+            usage("bata db connect");
+            note("Interactive only — use `bata db query` / `bata db url` headlessly.");
+            break;
+        case "studio":
+            log(`  ${colors.bold("bata db studio")} — open the table browser in your browser`);
+            log();
+            usage("bata db studio");
+            break;
+        default:
+            log(`  ${colors.bold("bata db")} — database commands`);
+            log();
+            usage("bata db connect          Open psql to your database");
+            usage("bata db url              Print connection string");
+            usage("bata db branches         List branches + compute status");
+            usage("bata db branch create    Create a new branch");
+            usage("bata db branch delete    Delete a branch");
+            usage("bata db studio           Open the table browser");
+            usage("bata db query <sql>      Run a SQL query (--branch <id> to target a branch)");
+            log();
+            note("Add --help to any subcommand for details (e.g. bata db query --help).");
+    }
+    log();
+}
 export async function handleDb(args) {
     const sub = args[0];
+    // A --help / -h anywhere prints usage for the subcommand and exits 0 WITHOUT
+    // any network call. This must run before dispatch so `db query --help` never
+    // treats "--help" as SQL and hits /v1/sql/execute.
+    if (hasHelpFlag(args)) {
+        dbHelp(sub);
+        return;
+    }
     switch (sub) {
         case "connect":
             return connect();
@@ -350,7 +480,7 @@ export async function handleDb(args) {
         case "studio":
             return studio();
         case "query":
-            return query(args.slice(1).join(" "));
+            return query(args.slice(1));
         default:
             emitError("INVALID_FLAG", `Unknown subcommand: db ${sub || ""}`, "Available: connect, url, branches, branch, studio, query");
     }

package/dist/commands/db.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/commands/db.test.js

@@ -0,0 +1,173 @@
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+const { get, post } = vi.hoisted(() => ({
+    get: vi.fn(async () => ({
+        ok: true,
+        status: 200,
+        data: { id: "proj_1", name: "demo", branches: [{ id: "br_primary", name: "main", is_primary: true, status: "ready" }] },
+    })),
+    post: vi.fn(async () => ({ ok: true, status: 200, data: { columns: ["n"], rows: [{ n: "1" }], rowCount: 1 } })),
+}));
+vi.mock("../api.js", () => ({
+    api: { get, post, del: vi.fn() },
+    resolveTeamId: vi.fn(async () => "team_test"),
+    // Mirror the real apiError so retryable mapping (which reads the server code)
+    // gets a realistic message; we don't need its exact format here.
+    apiError: (res, fallback) => {
+        const msg = res?.data?.error ?? fallback;
+        const code = res?.data?.code ? ` (${res.data.code})` : "";
+        return `${msg}${code}`;
+    },
+    asList: (data) => (Array.isArray(data) ? data : []),
+}));
+import { query, handleDb } from "./db.js";
+import { setRuntime } from "../config.js";
+let tmpHome;
+let logSpy;
+// process.exit must NOT actually exit the test runner. Throw a tagged error so
+// the handler unwinds at the exit point; tests catch it and read the code.
+class ExitError extends Error {
+    code;
+    constructor(code) {
+        super(`exit ${code}`);
+        this.code = code;
+    }
+}
+beforeEach(() => {
+    tmpHome = fs.mkdtempSync(path.join(os.tmpdir(), "bata-cli-db-test-"));
+    vi.stubEnv("HOME", tmpHome);
+    vi.stubEnv("USERPROFILE", tmpHome);
+    // A real credential + a default project so query() reaches the network seam.
+    fs.writeFileSync(path.join(tmpHome, ".batarc"), JSON.stringify({ defaultProject: "proj_1" }));
+    setRuntime({ apiKey: "test-token", apiUrl: "https://api.test.local", json: true, yes: false });
+    get.mockClear();
+    post.mockClear();
+    vi.spyOn(process, "exit").mockImplementation(((code) => {
+        throw new ExitError(code ?? 0);
+    }));
+    // Silence the JSON/decorative output so test logs stay clean.
+    logSpy = vi.spyOn(console, "log").mockImplementation(() => { });
+    vi.spyOn(console, "error").mockImplementation(() => { });
+});
+afterEach(() => {
+    vi.unstubAllEnvs();
+    vi.restoreAllMocks();
+    setRuntime({ json: false, yes: false });
+    fs.rmSync(tmpHome, { recursive: true, force: true });
+});
+/** Run a handler that's expected to call process.exit; return the exit code. */
+async function exitCodeOf(run) {
+    try {
+        await run();
+    }
+    catch (e) {
+        if (e instanceof ExitError)
+            return e.code;
+        throw e;
+    }
+    return 0; // handler returned without exiting (success path)
+}
+describe("db query — --help short-circuits before any network call", () => {
+    it("`db query --help` prints help and makes NO api call (exit 0)", async () => {
+        const code = await exitCodeOf(() => handleDb(["query", "--help"]));
+        expect(post).not.toHaveBeenCalled();
+        expect(get).not.toHaveBeenCalled();
+        expect(code).toBe(0);
+        // It actually printed usage, not a row result.
+        const printed = logSpy.mock.calls.map((c) => String(c[0])).join("\n");
+        expect(printed).toContain("bata db query");
+        expect(printed).toContain("--branch");
+    });
+    it("`db query -h` (short flag) also short-circuits with no api call", async () => {
+        const code = await exitCodeOf(() => handleDb(["query", "-h"]));
+        expect(post).not.toHaveBeenCalled();
+        expect(get).not.toHaveBeenCalled();
+        expect(code).toBe(0);
+    });
+    it("`db --help` prints general db help with no api call", async () => {
+        const code = await exitCodeOf(() => handleDb(["--help"]));
+        expect(post).not.toHaveBeenCalled();
+        expect(get).not.toHaveBeenCalled();
+        expect(code).toBe(0);
+    });
+});
+describe("db query — branch targeting", () => {
+    it("--branch <id> sets branch_id in the request body and skips primary lookup", async () => {
+        await exitCodeOf(() => query(["SELECT 1", "--branch", "br_explicit"]));
+        expect(post).toHaveBeenCalledTimes(1);
+        expect(post).toHaveBeenCalledWith("/v1/sql/execute", expect.objectContaining({ branch_id: "br_explicit", query: "SELECT 1" }), "test-token");
+        // Explicit branch → no need to resolve the primary.
+        expect(get).not.toHaveBeenCalled();
+    });
+    it("--branch=<id> (equals form) is also honored", async () => {
+        await exitCodeOf(() => query(["--branch=br_eq", "SELECT 2"]));
+        expect(post).toHaveBeenCalledWith("/v1/sql/execute", expect.objectContaining({ branch_id: "br_eq", query: "SELECT 2" }), "test-token");
+    });
+    it("without --branch, resolves the project's primary branch (default behavior)", async () => {
+        await exitCodeOf(() => query(["SELECT 1"]));
+        expect(get).toHaveBeenCalledTimes(1); // resolved primary
+        expect(post).toHaveBeenCalledWith("/v1/sql/execute", expect.objectContaining({ branch_id: "br_primary", query: "SELECT 1" }), "test-token");
+    });
+});
+describe("db query — retryable cold-start mapping (exit 6)", () => {
+    it("503 + { code: COMPUTE_STARTING } maps to exit 6 (retryable), not 1", async () => {
+        post.mockResolvedValueOnce({
+            ok: false,
+            status: 503,
+            data: { error: "compute is starting", code: "COMPUTE_STARTING" },
+        });
+        const code = await exitCodeOf(() => query(["SELECT 1", "--branch", "br_cold"]));
+        expect(code).toBe(6);
+    });
+    it("REGRESSION GUARD: a non-5xx status carrying { code: COMPUTE_STARTING } still maps to exit 6", async () => {
+        // The pre-fix code only looked at the HTTP status (>=500 || 0), so a
+        // COMPUTE_STARTING surfaced on, say, a 425 would have been CLI_ERROR (exit
+        // 1). This is the exact guard for the body-code inspection.
+        post.mockResolvedValueOnce({
+            ok: false,
+            status: 425,
+            data: { error: "compute is starting", code: "COMPUTE_STARTING" },
+        });
+        const code = await exitCodeOf(() => query(["SELECT 1", "--branch", "br_cold"]));
+        expect(code).toBe(6);
+    });
+    it("a connection-refused error body maps to exit 6", async () => {
+        post.mockResolvedValueOnce({
+            ok: false,
+            status: 0,
+            data: { error: "connect ECONNREFUSED 127.0.0.1:5432" },
+        });
+        const code = await exitCodeOf(() => query(["SELECT 1", "--branch", "br_cold"]));
+        expect(code).toBe(6);
+    });
+    it("a generic 5xx maps to exit 6", async () => {
+        post.mockResolvedValueOnce({ ok: false, status: 502, data: { error: "bad gateway" } });
+        const code = await exitCodeOf(() => query(["SELECT 1", "--branch", "br_cold"]));
+        expect(code).toBe(6);
+    });
+    it("a genuine SQL syntax error (200 with error field) stays exit 1, NOT retryable", async () => {
+        post.mockResolvedValueOnce({
+            ok: true,
+            status: 200,
+            data: { error: 'syntax error at or near "SELCT"' },
+        });
+        const code = await exitCodeOf(() => query(["SELCT 1", "--branch", "br_ok"]));
+        expect(code).toBe(1);
+    });
+    it("a 400 bad-input SQL error stays exit 1, NOT retryable", async () => {
+        post.mockResolvedValueOnce({
+            ok: false,
+            status: 400,
+            data: { error: "relation does not exist" },
+        });
+        const code = await exitCodeOf(() => query(["SELECT * FROM nope", "--branch", "br_ok"]));
+        expect(code).toBe(1);
+    });
+    it("a 401 stays auth (exit 4), not retryable", async () => {
+        post.mockResolvedValueOnce({ ok: false, status: 401, data: { error: "invalid key" } });
+        const code = await exitCodeOf(() => query(["SELECT 1", "--branch", "br_ok"]));
+        expect(code).toBe(4);
+    });
+});

package/dist/commands/projects.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/commands/projects.test.js

@@ -0,0 +1,104 @@
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+// --- Mock the network layer so no real HTTP happens and we can assert that the
+// --- DELETE call is (or isn't) invoked. This is the seam: deleteProject() calls
+// --- `api.del(...)`, so a spy here proves whether the delete actually proceeds.
+// `vi.hoisted` so the spy exists before the hoisted vi.mock factory runs.
+const { del, readlineQuestion } = vi.hoisted(() => ({
+    del: vi.fn(async () => ({ ok: true, status: 200, data: {} })),
+    // The interactive prompt seam: confirm() -> prompt() -> readline.question().
+    // Default answer is empty; a TTY test sets it to "n" to decline.
+    readlineQuestion: vi.fn((_q, cb) => cb("")),
+}));
+vi.mock("../api.js", () => ({
+    api: {
+        get: vi.fn(async () => ({ ok: true, status: 200, data: {} })),
+        post: vi.fn(async () => ({ ok: true, status: 200, data: {} })),
+        del,
+    },
+    // No real /v1/teams round-trip; deleteProject only needs an optional team id.
+    resolveTeamId: vi.fn(async () => "team_test"),
+    apiError: (_res, fallback) => fallback,
+    asList: (data) => (Array.isArray(data) ? data : []),
+}));
+// Mock readline so the interactive confirm() branch never blocks on real stdin.
+vi.mock("node:readline", () => ({
+    default: { createInterface: () => ({ question: readlineQuestion, close: () => { } }) },
+    createInterface: () => ({ question: readlineQuestion, close: () => { } }),
+}));
+// We deliberately do NOT mock ../config.js or ../utils/prompts.js — the whole
+// point of this test is to exercise the REAL confirmDestructive() + the REAL
+// runtime flag plumbing (setRuntime/isYes/isJsonMode), since that branch is the
+// destructive-headless contract under test.
+import { deleteProject } from "./projects.js";
+import { setRuntime } from "../config.js";
+let tmpHome;
+let realIsTTY;
+beforeEach(() => {
+    // Point ~/.batarc at a throwaway HOME so loadConfig/saveConfig never touch the
+    // developer's real config. os.homedir() reads HOME at call time (verified).
+    tmpHome = fs.mkdtempSync(path.join(os.tmpdir(), "bata-cli-test-"));
+    vi.stubEnv("HOME", tmpHome);
+    vi.stubEnv("USERPROFILE", tmpHome); // Windows parity
+    // requireToken() resolves the --api-key runtime value first, so a real
+    // credential exists without writing a config file.
+    setRuntime({ apiKey: "test-token", apiUrl: "https://api.test.local", json: false, yes: false });
+    del.mockClear();
+    readlineQuestion.mockClear();
+    readlineQuestion.mockImplementation((_q, cb) => cb(""));
+    // Snapshot isTTY so individual tests can override it and we restore after.
+    realIsTTY = Object.getOwnPropertyDescriptor(process.stdin, "isTTY");
+});
+afterEach(() => {
+    vi.unstubAllEnvs();
+    vi.restoreAllMocks();
+    setRuntime({ json: false, yes: false });
+    if (realIsTTY) {
+        Object.defineProperty(process.stdin, "isTTY", realIsTTY);
+    }
+    fs.rmSync(tmpHome, { recursive: true, force: true });
+});
+function setTTY(value) {
+    Object.defineProperty(process.stdin, "isTTY", { value, configurable: true });
+}
+describe("projects delete — destructive headless contract", () => {
+    it("REGRESSION GUARD: with --yes, does NOT prompt and the DELETE actually proceeds", async () => {
+        // The original bug: headless `--yes` exited 0 having deleted NOTHING.
+        // This is the exact guard — if deleteProject silently skipped the delete,
+        // `del` would never be called and this expectation would fail.
+        setTTY(true); // even on a TTY, --yes must skip the prompt and proceed
+        setRuntime({ yes: true });
+        await deleteProject("proj_123");
+        expect(del).toHaveBeenCalledTimes(1);
+        expect(del).toHaveBeenCalledWith("/v1/projects/proj_123", "test-token", expect.objectContaining({ team_id: "team_test" }));
+    });
+    it("in --json mode, proceeds without prompting and deletes", async () => {
+        setTTY(true);
+        setRuntime({ json: true });
+        await deleteProject("proj_json");
+        expect(del).toHaveBeenCalledTimes(1);
+        expect(del).toHaveBeenCalledWith("/v1/projects/proj_json", "test-token", expect.anything());
+    });
+    it("when stdin is not a TTY (agent / piped / CI), proceeds and deletes without --yes", async () => {
+        // This is the CLI's whole purpose: unattended deletes must go through.
+        setTTY(false);
+        setRuntime({ yes: false, json: false });
+        await deleteProject("proj_pipe");
+        expect(del).toHaveBeenCalledTimes(1);
+        expect(del).toHaveBeenCalledWith("/v1/projects/proj_pipe", "test-token", expect.anything());
+    });
+    it("interactive TTY without --yes WOULD prompt; answering no aborts (no DELETE)", async () => {
+        // Covers the interactive branch of confirmDestructive(): it must ask, and a
+        // "no" answer must NOT call the delete API. The mocked readline (above) is
+        // the seam confirm() -> prompt() uses; we answer "n" to decline.
+        setTTY(true);
+        setRuntime({ yes: false, json: false });
+        readlineQuestion.mockImplementation((_q, cb) => cb("n"));
+        await deleteProject("proj_keep");
+        expect(readlineQuestion).toHaveBeenCalledTimes(1); // it DID prompt
+        expect(readlineQuestion.mock.calls[0][0]).toContain("Delete project");
+        expect(del).not.toHaveBeenCalled(); // declined → no destructive call
+    });
+});

package/dist/index.js

@@ -14,8 +14,8 @@ import { usage } from "./commands/usage.js";
 import { parseGlobalFlags } from "./args.js";
 import { isJsonMode } from "./config.js";
 import { colors, log, banner } from "./utils/logger.js";
-import { exitCodeFor } from "./utils/errors.js";
-const VERSION = "0.1.2";
+import { exitCodeFor, isRetryable } from "./utils/errors.js";
+const VERSION = "0.1.3";
 function help() {
     banner();
     log(`  ${colors.bold("Usage")}`);
@@ -43,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`);
@@ -84,7 +84,7 @@ function help() {
     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(`    ${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();
@@ -188,8 +188,11 @@ async function main() {
         // 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";
+        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, hint: "" }, null, 2));
         }

package/dist/utils/errors.d.ts

@@ -13,9 +13,27 @@
  *   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)
+ *   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" | "GATE_TRIPPED";
+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;
 /**

package/dist/utils/errors.js

@@ -13,10 +13,35 @@
  *   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)
+ *   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) {
@@ -37,6 +62,7 @@ export function exitCodeFor(code) {
             return 5;
         case "API_UNAVAILABLE":
         case "TIMEOUT":
+        case "COMPUTE_STARTING":
             return 6;
         case "GATE_TRIPPED":
             return 2;

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.2")} ${colors.dim("— serverless Postgres platform")}`);
+    log(`  ${colors.cyan(colors.bold("BataDB"))} ${colors.dim("v0.1.3")} ${colors.dim("— serverless Postgres platform")}`);
     log();
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@batadata/cli",
-  "version": "0.1.2",
+  "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"