@batadata/cli 0.2.13 → 0.2.15

package/dist/api.js

@@ -3,6 +3,7 @@ import * as http from "node:http";
 import { URL } from "node:url";
 import { getApiUrl, loadConfig, getTokenSource, isJsonMode } from "./config.js";
 import { colors } from "./utils/logger.js";
+import { VERSION } from "./version.js";
 export async function request(method, path, options = {}) {
     const baseUrl = getApiUrl();
     const url = new URL(path, baseUrl);
@@ -15,7 +16,7 @@ export async function request(method, path, options = {}) {
     }
     const headers = {
         "Content-Type": "application/json",
-        "User-Agent": "@batadata/cli 0.1.4",
+        "User-Agent": `@batadata/cli ${VERSION}`,
     };
     if (options.token) {
         headers["Authorization"] = `Bearer ${options.token}`;

package/dist/commands/doctor.d.ts

@@ -0,0 +1,26 @@
+/**
+ * bata doctor: run turbine's index doctor against a branch and (optionally)
+ * upload the report into the project's index-advice ledger.
+ *
+ * `turbine doctor --json` (turbine-orm >= 0.46) emits a versioned report
+ * (schemaVersion 1) of missing-index findings scored against live statistics.
+ * This command wires that to BataDB so a CI job can keep the advice ledger
+ * current with one line, instead of hand-rolling a curl of a piped JSON blob.
+ *
+ * Nothing here interprets the report: the control plane owns the contract, and
+ * an unknown schemaVersion is its 400 to give, not ours to guess at.
+ */
+export interface DoctorArgs {
+    project?: string;
+    branch?: string;
+    /** Skip the upload and just print the report. */
+    dryRun: boolean;
+    /** Pass `--unused`/`--audit` through to turbine doctor. */
+    unused: boolean;
+    audit: boolean;
+    help: boolean;
+}
+export declare function parseDoctorArgs(args: string[]): DoctorArgs | {
+    error: string;
+};
+export declare function doctorCommand(args: string[]): Promise<void>;

package/dist/commands/doctor.js

@@ -0,0 +1,201 @@
+/**
+ * bata doctor: run turbine's index doctor against a branch and (optionally)
+ * upload the report into the project's index-advice ledger.
+ *
+ * `turbine doctor --json` (turbine-orm >= 0.46) emits a versioned report
+ * (schemaVersion 1) of missing-index findings scored against live statistics.
+ * This command wires that to BataDB so a CI job can keep the advice ledger
+ * current with one line, instead of hand-rolling a curl of a piped JSON blob.
+ *
+ * Nothing here interprets the report: the control plane owns the contract, and
+ * an unknown schemaVersion is its 400 to give, not ours to guess at.
+ */
+import { spawn } from "node:child_process";
+import { api, apiError } from "../api.js";
+import { requireToken, isJsonMode } from "../config.js";
+import { colors, log, spinner, info as logInfo } from "../utils/logger.js";
+import { emitError } from "../utils/errors.js";
+import { resolveProjectId, readLinkFile } from "../link.js";
+export function parseDoctorArgs(args) {
+    const out = { dryRun: false, unused: false, audit: false, help: false };
+    for (let i = 0; i < args.length; i++) {
+        const a = args[i];
+        const takeVal = (flag) => {
+            const next = args[i + 1];
+            if (next === undefined || next.startsWith("-"))
+                return undefined;
+            i++;
+            return next;
+        };
+        if (a === "--help" || a === "-h") {
+            out.help = true;
+        }
+        else if (a === "--project" || a === "-p") {
+            const v = takeVal("--project");
+            if (v === undefined)
+                return { error: "--project requires a value" };
+            out.project = v;
+        }
+        else if (a.startsWith("--project=")) {
+            out.project = a.slice("--project=".length);
+        }
+        else if (a === "--branch" || a === "-b") {
+            const v = takeVal("--branch");
+            if (v === undefined)
+                return { error: "--branch requires a value" };
+            out.branch = v;
+        }
+        else if (a.startsWith("--branch=")) {
+            out.branch = a.slice("--branch=".length);
+        }
+        else if (a === "--dry-run") {
+            out.dryRun = true;
+        }
+        else if (a === "--unused") {
+            out.unused = true;
+        }
+        else if (a === "--audit") {
+            out.audit = true;
+        }
+        else {
+            return { error: `Unknown argument: ${a}` };
+        }
+    }
+    return out;
+}
+function doctorHelp() {
+    log();
+    log(`  ${colors.bold("bata doctor")}: index advice from turbine doctor, into your ledger`);
+    log();
+    log(`  ${colors.dim("Usage:")}`);
+    log(`    bata doctor upload [--project <id>] [--branch <name|id>] [--dry-run]`);
+    log();
+    log(`  ${colors.dim("Runs `turbine doctor --json` against the branch's direct connection and")}`);
+    log(`  ${colors.dim("imports the findings into the project's index-advice ledger. Re-imports")}`);
+    log(`  ${colors.dim("refresh the numbers; advice you dismissed stays dismissed.")}`);
+    log();
+    log(`  ${colors.dim("--project <id>       Target project (default: linked/default project)")}`);
+    log(`  ${colors.dim("--branch <name|id>   Target branch (default: checked-out, else primary)")}`);
+    log(`  ${colors.dim("--dry-run            Print the report; do not upload")}`);
+    log(`  ${colors.dim("--unused             Also collect never-scanned/redundant index advice")}`);
+    log(`  ${colors.dim("--audit              Also audit previously-suggested indexes")}`);
+    log();
+    log(`  ${colors.dim("Requires turbine-orm >= 0.46 (fetched via npx if not installed).")}`);
+    log();
+}
+/** Run `turbine doctor --json` and capture stdout. */
+function runTurbineDoctor(databaseUrl, flags) {
+    return new Promise((resolve) => {
+        const child = spawn("npx", ["--yes", "turbine-orm@latest", "doctor", "--json", ...flags], {
+            env: { ...process.env, DATABASE_URL: databaseUrl },
+            stdio: ["ignore", "pipe", "pipe"],
+        });
+        let stdout = "";
+        let stderr = "";
+        child.stdout.on("data", (d) => (stdout += d.toString()));
+        child.stderr.on("data", (d) => (stderr += d.toString()));
+        child.on("error", (err) => {
+            resolve({ ok: false, error: `Could not run turbine doctor: ${err.message}` });
+        });
+        child.on("close", (code) => {
+            // doctor exits non-zero when it HAS findings, which is not a failure for
+            // us: parse first, and only treat unparseable output as an error.
+            const start = stdout.indexOf("{");
+            if (start === -1) {
+                resolve({
+                    ok: false,
+                    error: `turbine doctor produced no JSON report (exit ${code}). ${stderr.trim().slice(0, 300)}`,
+                });
+                return;
+            }
+            try {
+                resolve({ ok: true, report: JSON.parse(stdout.slice(start)) });
+            }
+            catch (err) {
+                resolve({ ok: false, error: `Could not parse the doctor report: ${String(err)}` });
+            }
+        });
+    });
+}
+export async function doctorCommand(args) {
+    const sub = args[0] === "upload" ? args.slice(1) : args;
+    const parsed = parseDoctorArgs(sub);
+    if ("error" in parsed) {
+        emitError("INVALID_FLAG", parsed.error, "Usage: bata doctor upload [--project <id>] [--branch <name|id>]");
+    }
+    if (parsed.help) {
+        doctorHelp();
+        return;
+    }
+    const token = requireToken();
+    const projectId = parsed.project ?? resolveProjectId().projectId;
+    if (!projectId) {
+        emitError("NO_PROJECT", "No project specified.", "Pass --project <id>, or run `bata link <project>` to set a default.");
+    }
+    const s = spinner("Fetching connection info");
+    const connRes = await api.get(`/v1/connection-info/${projectId}`, token, { reveal: "true" });
+    if (!connRes.ok || !connRes.data?.connections?.length) {
+        s.stop();
+        emitError(connRes.status >= 500 || connRes.status === 0 ? "API_UNAVAILABLE" : "NOT_FOUND", apiError(connRes, "Could not fetch connection info for this project."), "");
+    }
+    // Branch precedence matches `db query`: --branch, else the checked-out branch
+    // when it belongs to this project, else primary.
+    const link = readLinkFile()?.link;
+    const pinned = link && link.projectId === projectId ? link.branchId ?? undefined : undefined;
+    const branchRef = parsed.branch ?? pinned;
+    const conns = connRes.data.connections;
+    const conn = branchRef
+        ? conns.find((c) => c.branch_id === branchRef || c.branch_name === branchRef)
+        : conns.find((c) => c.is_primary) ?? conns[0];
+    if (!conn?.direct) {
+        s.stop();
+        emitError("BRANCH_NOT_FOUND", branchRef
+            ? `Branch "${branchRef}" not found, or it has no direct connection.`
+            : "No direct connection string available for this project.", "List branches with: bata db branches --json");
+    }
+    s.update("Running turbine doctor");
+    const flags = [];
+    if (parsed.unused)
+        flags.push("--unused");
+    if (parsed.audit)
+        flags.push("--audit");
+    const result = await runTurbineDoctor(conn.direct, flags);
+    s.stop();
+    if (!result.ok) {
+        emitError("CLI_ERROR", result.error, "Requires turbine-orm >= 0.46 for `doctor --json`.");
+    }
+    const report = result.report;
+    const findingCount = Array.isArray(report.findings) ? report.findings.length : 0;
+    if (parsed.dryRun) {
+        if (isJsonMode()) {
+            log(JSON.stringify(report, null, 2));
+        }
+        else {
+            logInfo(`${findingCount} finding(s); not uploaded (--dry-run)`);
+            log(JSON.stringify(report, null, 2));
+        }
+        return;
+    }
+    const s2 = spinner("Uploading to the index-advice ledger");
+    const importRes = await api.post(`/v1/projects/${projectId}/index-advice/import`, report, token);
+    s2.stop();
+    if (!importRes.ok) {
+        emitError(importRes.status === 401 || importRes.status === 403
+            ? "INVALID_KEY"
+            : importRes.status >= 500 || importRes.status === 0
+                ? "API_UNAVAILABLE"
+                : "CLI_ERROR", apiError(importRes, "Could not import the doctor report."), "");
+    }
+    const data = importRes.data;
+    if (isJsonMode()) {
+        log(JSON.stringify({ ...data, branch: conn.branch_name ?? conn.branch_id }, null, 2));
+        return;
+    }
+    logInfo(`Imported ${colors.bold(String(data.imported))} new and refreshed ${colors.bold(String(data.updated))} existing recommendation(s)` +
+        (conn.branch_name ? ` from ${colors.cyan(conn.branch_name)}` : ""));
+    if (data.invalidIndexes > 0) {
+        log(`  ${colors.dim(`${data.invalidIndexes} invalid index(es) reported; see the console for cleanup SQL.`)}`);
+    }
+    log(`  ${colors.dim("Review them in the console under Insights, or with:")}`);
+    log(`  ${colors.dim(`bata db query "..." --json`)} ${colors.dim("/ GET /v1/projects/" + projectId + "/index-advice")}`);
+}

package/dist/index.js

@@ -18,16 +18,13 @@ import { handleRestore } from "./commands/restore.js";
 import { handlePowdb } from "./commands/powdb.js";
 import { importDb } from "./commands/import.js";
 import { studio } from "./commands/studio.js";
+import { doctorCommand } from "./commands/doctor.js";
 import { link, unlink } from "./commands/link.js";
 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";
-import { createRequire } from "node:module";
-// Read the version from package.json (dist/index.js → ../package.json) instead
-// of a hardcoded constant — the constant sat at "0.1.4" while releases shipped
-// through 0.1.19, so every published CLI misreported `--version`.
-const VERSION = createRequire(import.meta.url)("../package.json").version;
+import { VERSION } from "./version.js";
 function help() {
     banner();
     log(`  ${colors.bold("Usage")}`);
@@ -65,6 +62,7 @@ function help() {
     log(`    ${colors.cyan("db branch checkout")} Pin a branch into ${colors.dim(".batadata/project.json")}`);
     log(`    ${colors.cyan("db studio")}          Open table browser in browser`);
     log(`    ${colors.cyan("studio")}             Run Turbine Studio locally against a branch ${colors.dim("(local UI, direct TCP)")}`);
+    log(`    ${colors.cyan("doctor upload")}      Import turbine index advice into the project ledger`);
     log(`    ${colors.cyan("db query")}           Run a SQL query ${colors.dim("(--branch <id> to target a branch)")}`);
     log();
     log(`  ${colors.bold("Compute")}`);
@@ -223,6 +221,9 @@ async function main() {
                 await importDb(rest);
                 break;
             // Local Turbine Studio against a branch
+            case "doctor":
+                await doctorCommand(rest);
+                break;
             case "studio":
                 await studio(rest);
                 break;

package/dist/utils/logger.js

@@ -1,4 +1,5 @@
 import { isJsonMode } from "../config.js";
+import { VERSION } from "../version.js";
 // ANSI color codes
 const ESC = "\x1b[";
 const RESET = `${ESC}0m`;
@@ -124,6 +125,6 @@ export function kvList(items) {
 // Banner
 export function banner() {
     log();
-    log(`  ${colors.cyan(colors.bold("BataDB"))} ${colors.dim("v0.1.4")} ${colors.dim("— serverless Postgres platform")}`);
+    log(`  ${colors.cyan(colors.bold("BataDB"))} ${colors.dim(`v${VERSION}`)} ${colors.dim("— serverless Postgres platform")}`);
     log();
 }

package/dist/version.d.ts

@@ -0,0 +1 @@
+export declare const VERSION: string;

package/dist/version.js

@@ -0,0 +1,11 @@
+import { createRequire } from "node:module";
+// The single source of truth for the CLI's version.
+//
+// This used to be a hardcoded constant copied into three places, and all three
+// drifted: `--version` read 0.2.12, the help banner said v0.1.4, and the
+// User-Agent we sent to the API claimed 0.1.4 as well. A bug report citing the
+// banner version sent us hunting through the wrong release.
+//
+// Resolved relative to this module's own URL, so it works from dist/version.js
+// regardless of how deeply the importing module is nested.
+export const VERSION = createRequire(import.meta.url)("../package.json").version;

package/package.json

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