@batadata/cli 0.1.3 → 0.1.4

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.3",
+        "User-Agent": "@batadata/cli 0.1.4",
     };
     if (options.token) {
         headers["Authorization"] = `Bearer ${options.token}`;

package/dist/commands/db.js

@@ -36,26 +36,46 @@ function formatDate(iso) {
  * when the compute is ready to serve a query without a cold start.
  */
 function branchStatusLabel(b) {
-    const base = b.computeStatus || b.status || "-";
+    const base = b.computeStatus || "-";
     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
- * the primary, falling back to the first branch. Returns null if the project
- * has no branches or the lookup failed.
+ * List a project's branches (GET /v1/projects/:id), each enriched by the server
+ * with computeStatus + ready. Returns null if the lookup failed.
  */
-async function getPrimaryBranch(projectId, token, teamId) {
+async function listBranches(projectId, token, teamId) {
     const query = {};
     if (teamId)
         query.team_id = teamId;
     const res = await api.get(`/v1/projects/${projectId}`, token, query);
     if (!res.ok)
         return null;
-    const list = res.data.branches ?? [];
-    return list.find((b) => b.is_primary) ?? list[0] ?? null;
+    return { branches: res.data.branches ?? [], projectName: res.data.name };
+}
+/**
+ * Resolve a project's primary branch (the one to run a query against), falling
+ * back to the first branch. Returns null if the project has no branches or the
+ * lookup failed.
+ */
+async function getPrimaryBranch(projectId, token, teamId) {
+    const result = await listBranches(projectId, token, teamId);
+    if (!result)
+        return null;
+    return result.branches.find((b) => b.isPrimary) ?? result.branches[0] ?? null;
+}
+/**
+ * Resolve a `--branch` reference — which may be a branch ID **or** a branch
+ * name — to a concrete branch. Agents naturally pass the name (the same string
+ * they used with `db branch create`), so accepting only an id was a footgun
+ * ("Branch not found"). Returns null if no branch matches.
+ */
+async function resolveBranchRef(projectId, token, teamId, ref) {
+    const result = await listBranches(projectId, token, teamId);
+    if (!result)
+        return null;
+    return result.branches.find((b) => b.id === ref || b.name === ref) ?? null;
 }
 export async function connect() {
     // psql is an interactive session — there's no headless equivalent. Don't spawn
@@ -123,38 +143,31 @@ export async function branches() {
         emitError("NO_PROJECT", "No default project set.", "Set one with: bata projects info <id>");
     }
     const s = jsonMode ? null : spinner("Fetching branches");
-    const query = {};
-    if (config.defaultTeam)
-        query.team_id = config.defaultTeam;
-    const res = await api.get(`/v1/projects/${projectId}`, token, query);
+    const result = await listBranches(projectId, token, config.defaultTeam);
     s?.stop();
-    if (!res.ok) {
-        emitError(res.status === 401 || res.status === 403 ? "INVALID_KEY"
-            : res.status === 404 ? "NO_PROJECT"
-                : res.status >= 500 || res.status === 0 ? "API_UNAVAILABLE"
-                    : "CLI_ERROR", apiError(res, "Failed to fetch branches"), "");
+    if (!result) {
+        emitError("API_UNAVAILABLE", "Failed to fetch branches.", "");
     }
-    const branchList = res.data.branches || [];
+    const branchList = result.branches;
     if (jsonMode) {
         json({
             project_id: projectId,
-            project_name: res.data.name,
+            project_name: result.projectName,
             branches: branchList.map((b) => ({
                 id: b.id,
                 name: b.name,
-                is_primary: b.is_primary,
-                status: b.status,
+                is_primary: b.isPrimary ?? false,
                 // 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,
+                created_at: b.createdAt ?? null,
             })),
             count: branchList.length,
         });
         return;
     }
-    heading(`Branches — ${res.data.name}`);
+    heading(`Branches — ${result.projectName}`);
     if (branchList.length === 0) {
         log(`  ${colors.dim("No branches found.")}`);
         log();
@@ -162,11 +175,11 @@ export async function branches() {
     }
     table(["NAME", "PRIMARY", "STATUS", "CREATED"], branchList.map((b) => [
         b.name,
-        b.is_primary ? colors.green("yes") : "-",
-        // Prefer the live compute lifecycle (computeStatus); fall back to the
-        // branch row status. Mark ready with a check so the column is scannable.
+        b.isPrimary ? colors.green("yes") : "-",
+        // Live compute lifecycle (computeStatus), with a check once ready so the
+        // column is scannable.
         branchStatusLabel(b),
-        formatDate(b.created_at),
+        formatDate(b.createdAt ?? ""),
     ]));
     log();
 }
@@ -275,10 +288,11 @@ export async function studio() {
     openBrowser(studioUrl);
 }
 /**
- * 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.
+ * Pull a `--branch <ref>` / `--branch=<ref>` flag out of the query args and
+ * return the explicit branch ref — an id OR a name, resolved later — plus the
+ * remaining args, which join into the SQL string. Keeps `db query`
+ * order-independent (the flag can sit before or after the SQL) and consistent
+ * with how global flags are parsed.
  */
 function parseBranchFlag(args) {
     let branchId;
@@ -311,11 +325,22 @@ export async function query(args = []) {
         emitError("NO_PROJECT", "No default project set.", "Set one with: bata projects info <id>");
     }
     const s = jsonMode ? null : spinner("Running query");
-    // 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.)
-    let branchId_ = branchId;
-    if (!branchId_) {
+    // Target branch: an explicit --branch <id-or-name> 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.) We
+    // resolve the --branch value against the project's branch list so a NAME
+    // works too — sending a name straight through as branch_id 404'd ("Branch
+    // not found").
+    let branchId_;
+    if (branchId) {
+        const branch = await resolveBranchRef(projectId, token, config.defaultTeam, branchId);
+        if (!branch) {
+            s?.stop();
+            emitError("BRANCH_NOT_FOUND", `Branch "${branchId}" not found in this project.`, "List branches with: bata db branches --json");
+        }
+        branchId_ = branch.id;
+    }
+    else {
         const branch = await getPrimaryBranch(projectId, token, config.defaultTeam);
         if (!branch) {
             s?.stop();
@@ -401,9 +426,9 @@ function dbHelp(sub) {
             log(`  ${colors.bold("bata db query")} — run a SQL query against a branch`);
             log();
             usage('bata db query "SELECT 1"');
-            usage("bata db query <sql> [--branch <branch_id>] [--json]");
+            usage("bata db query <sql> [--branch <id-or-name>] [--json]");
             log();
-            note("--branch <branch_id>   Target a specific branch (default: the project's primary)");
+            note("--branch <id-or-name>  Target a specific branch by id OR name (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.");
@@ -447,7 +472,7 @@ function dbHelp(sub) {
             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)");
+            usage("bata db query <sql>      Run a SQL query (--branch <id-or-name> to target a branch)");
             log();
             note("Add --help to any subcommand for details (e.g. bata db query --help).");
     }

package/dist/commands/db.test.js

@@ -6,7 +6,17 @@ 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" }] },
+        // Shape matches GET /v1/projects/:id: camelCase branch fields enriched
+        // with computeStatus + ready. `feature` is a second, non-primary branch
+        // so name/id resolution has something to match.
+        data: {
+            id: "proj_1",
+            name: "demo",
+            branches: [
+                { id: "br_primary", name: "main", isPrimary: true, computeStatus: "active", ready: true },
+                { id: "br_feature", name: "feature", isPrimary: false, computeStatus: "idle", ready: false },
+            ],
+        },
     })),
     post: vi.fn(async () => ({ ok: true, status: 200, data: { columns: ["n"], rows: [{ n: "1" }], rowCount: 1 } })),
 }));
@@ -94,16 +104,26 @@ describe("db query — --help short-circuits before any network call", () => {
     });
 });
 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"]));
+    it("--branch <id> resolves to that branch and sets branch_id", async () => {
+        await exitCodeOf(() => query(["SELECT 1", "--branch", "br_feature"]));
         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();
+        expect(post).toHaveBeenCalledWith("/v1/sql/execute", expect.objectContaining({ branch_id: "br_feature", query: "SELECT 1" }), "test-token");
+    });
+    it("--branch <name> resolves the NAME to the branch id (was 'Branch not found')", async () => {
+        await exitCodeOf(() => query(["SELECT 1", "--branch", "feature"]));
+        expect(post).toHaveBeenCalledTimes(1);
+        expect(post).toHaveBeenCalledWith("/v1/sql/execute", 
+        // Resolved the NAME "feature" → its id "br_feature".
+        expect.objectContaining({ branch_id: "br_feature", query: "SELECT 1" }), "test-token");
     });
-    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("--branch=<name> (equals form) is also resolved", async () => {
+        await exitCodeOf(() => query(["--branch=feature", "SELECT 2"]));
+        expect(post).toHaveBeenCalledWith("/v1/sql/execute", expect.objectContaining({ branch_id: "br_feature", query: "SELECT 2" }), "test-token");
+    });
+    it("--branch <unknown> exits 5 (not-found) and never runs a query", async () => {
+        const code = await exitCodeOf(() => query(["SELECT 1", "--branch", "does-not-exist"]));
+        expect(code).toBe(5);
+        expect(post).not.toHaveBeenCalled();
     });
     it("without --branch, resolves the project's primary branch (default behavior)", async () => {
         await exitCodeOf(() => query(["SELECT 1"]));
@@ -118,7 +138,7 @@ describe("db query — retryable cold-start mapping (exit 6)", () => {
             status: 503,
             data: { error: "compute is starting", code: "COMPUTE_STARTING" },
         });
-        const code = await exitCodeOf(() => query(["SELECT 1", "--branch", "br_cold"]));
+        const code = await exitCodeOf(() => query(["SELECT 1", "--branch", "feature"]));
         expect(code).toBe(6);
     });
     it("REGRESSION GUARD: a non-5xx status carrying { code: COMPUTE_STARTING } still maps to exit 6", async () => {
@@ -130,7 +150,7 @@ describe("db query — retryable cold-start mapping (exit 6)", () => {
             status: 425,
             data: { error: "compute is starting", code: "COMPUTE_STARTING" },
         });
-        const code = await exitCodeOf(() => query(["SELECT 1", "--branch", "br_cold"]));
+        const code = await exitCodeOf(() => query(["SELECT 1", "--branch", "feature"]));
         expect(code).toBe(6);
     });
     it("a connection-refused error body maps to exit 6", async () => {
@@ -139,12 +159,12 @@ describe("db query — retryable cold-start mapping (exit 6)", () => {
             status: 0,
             data: { error: "connect ECONNREFUSED 127.0.0.1:5432" },
         });
-        const code = await exitCodeOf(() => query(["SELECT 1", "--branch", "br_cold"]));
+        const code = await exitCodeOf(() => query(["SELECT 1", "--branch", "feature"]));
         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"]));
+        const code = await exitCodeOf(() => query(["SELECT 1", "--branch", "feature"]));
         expect(code).toBe(6);
     });
     it("a genuine SQL syntax error (200 with error field) stays exit 1, NOT retryable", async () => {
@@ -153,7 +173,7 @@ describe("db query — retryable cold-start mapping (exit 6)", () => {
             status: 200,
             data: { error: 'syntax error at or near "SELCT"' },
         });
-        const code = await exitCodeOf(() => query(["SELCT 1", "--branch", "br_ok"]));
+        const code = await exitCodeOf(() => query(["SELCT 1", "--branch", "feature"]));
         expect(code).toBe(1);
     });
     it("a 400 bad-input SQL error stays exit 1, NOT retryable", async () => {
@@ -162,12 +182,12 @@ describe("db query — retryable cold-start mapping (exit 6)", () => {
             status: 400,
             data: { error: "relation does not exist" },
         });
-        const code = await exitCodeOf(() => query(["SELECT * FROM nope", "--branch", "br_ok"]));
+        const code = await exitCodeOf(() => query(["SELECT * FROM nope", "--branch", "feature"]));
         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"]));
+        const code = await exitCodeOf(() => query(["SELECT 1", "--branch", "feature"]));
         expect(code).toBe(4);
     });
 });

package/dist/index.js

@@ -15,7 +15,7 @@ import { parseGlobalFlags } from "./args.js";
 import { isJsonMode } from "./config.js";
 import { colors, log, banner } from "./utils/logger.js";
 import { exitCodeFor, isRetryable } from "./utils/errors.js";
-const VERSION = "0.1.3";
+const VERSION = "0.1.4";
 function help() {
     banner();
     log(`  ${colors.bold("Usage")}`);

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

package/package.json

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