ardent-cli 0.0.42 → 0.0.44

package/dist/index.js

@@ -399,6 +399,16 @@ function findConnectorById(connectors, connectorId) {
   }
   return void 0;
 }
+var CurrentConnectorSelectionError = class extends Error {
+  code;
+  detailLines;
+  constructor(code, message, detailLines = []) {
+    super(message);
+    this.name = "CurrentConnectorSelectionError";
+    this.code = code;
+    this.detailLines = detailLines;
+  }
+};
 function reconcileSelectedConnector(connectors) {
   const currentConnectorId = getConfig("currentConnectorId");
   if (currentConnectorId) {
@@ -417,13 +427,27 @@ function reconcileSelectedConnector(connectors) {
   }
   return void 0;
 }
-async function requireCurrentConnectorId() {
+function printCurrentConnectorSelectionError(error) {
+  console.error(`\u2717 ${error.message}`);
+  for (const detailLine of error.detailLines) {
+    console.error(detailLine);
+  }
+}
+async function resolveCurrentConnectorId() {
   const currentProjectId = getConfig("currentProjectId");
   if (!currentProjectId) {
-    console.error("\u2717 No current project set. Switch to a project first:");
-    console.error("  ardent project list");
-    console.error("  ardent project switch <name>");
-    process.exit(1);
+    throw new CurrentConnectorSelectionError(
+      "no_current_project",
+      "No current project set. Switch to a project first.",
+      ["  ardent project list", "  ardent project switch <name>"]
+    );
+  }
+  const token = getToken();
+  if (!token) {
+    throw new CurrentConnectorSelectionError(
+      "not_authenticated",
+      "Not authenticated. Run: ardent login"
+    );
   }
   const result = await api.get(
     `/v1/cli/connectors?project_id=${currentProjectId}`
@@ -437,15 +461,21 @@ async function requireCurrentConnectorId() {
     return selectedConnector.id;
   }
   if (result.connectors.length === 0) {
-    console.error("\u2717 No connectors found.");
-    console.error("  Create one with: ardent connector create postgresql <url>");
-  } else {
-    console.error("\u2717 Previously selected connector is no longer available.");
-    console.error("  Select one of your current connectors:");
-    console.error("  ardent connector list");
-    console.error("  ardent connector switch <name>");
+    throw new CurrentConnectorSelectionError(
+      "no_connectors",
+      "No connectors found.",
+      ["  Create one with: ardent connector create postgresql <url>"]
+    );
   }
-  process.exit(1);
+  throw new CurrentConnectorSelectionError(
+    "connector_unavailable",
+    "Previously selected connector is no longer available.",
+    [
+      "  Select one of your current connectors:",
+      "  ardent connector list",
+      "  ardent connector switch <name>"
+    ]
+  );
 }
 
 // src/lib/telemetry.ts
@@ -505,11 +535,100 @@ function identifyUser(userId, personProperties = {}) {
   }).finally(() => clearTimeout(timeout));
 }
 
+// src/lib/branch_output.ts
+var BRANCH_JSON_SCHEMA_VERSION = 1;
+function buildBranchJson({
+  branch,
+  warning = null,
+  currentBranchName
+}) {
+  return {
+    schema_version: BRANCH_JSON_SCHEMA_VERSION,
+    id: branch.id,
+    name: branch.name,
+    connector_id: branch.connector_id,
+    service_type: branch.service_type,
+    status: branch.status,
+    branch_url: resolvePrintableUrl(branch),
+    created_at: branch.created_at,
+    last_branch_activity: branch.last_branch_activity ?? null,
+    current: currentBranchName !== void 0 && currentBranchName === branch.name,
+    warning
+  };
+}
+function renderBranchJson(payload) {
+  return JSON.stringify(payload) + "\n";
+}
+function renderBranchJsonError(code, message) {
+  const envelope = {
+    schema_version: BRANCH_JSON_SCHEMA_VERSION,
+    error: { code, message }
+  };
+  return JSON.stringify(envelope) + "\n";
+}
+function resolveOutputMode(options) {
+  const hasFormat = options.format !== void 0;
+  const hasPrintUrl = options.printUrl === true;
+  if (hasFormat && hasPrintUrl) {
+    return {
+      mode: "pretty",
+      error: "--format and --print-url are mutually exclusive"
+    };
+  }
+  if (hasFormat) {
+    if (options.format !== "json") {
+      return {
+        mode: "pretty",
+        error: `Unsupported --format value: ${options.format}. Supported: json`
+      };
+    }
+    return { mode: "json" };
+  }
+  if (hasPrintUrl) {
+    return { mode: "print-url" };
+  }
+  return { mode: "pretty" };
+}
+function resolvePrintableUrl(branch) {
+  if (!branch.branch_url) {
+    return null;
+  }
+  return branch.branch_url;
+}
+function isMachineReadableBranchInvocation(args2) {
+  let branchIndex = -1;
+  for (let index = 0; index < args2.length; index += 1) {
+    if (args2[index] === "branch") {
+      branchIndex = index;
+      break;
+    }
+  }
+  if (branchIndex === -1) {
+    return false;
+  }
+  const branchSubcommand = args2[branchIndex + 1];
+  if (branchSubcommand !== "create" && branchSubcommand !== "info") {
+    return false;
+  }
+  for (const arg of args2.slice(branchIndex + 2)) {
+    if (arg === "--print-url" || arg === "--format" || arg.startsWith("--format=")) {
+      return true;
+    }
+  }
+  return false;
+}
+
 // src/commands/branch/create.ts
 async function createAction(name, options) {
+  const modeResolution = resolveOutputMode(options);
+  if (modeResolution.error) {
+    console.error(`\u2717 ${modeResolution.error}`);
+    process.exit(2);
+  }
+  const mode = modeResolution.mode;
   try {
     const startTime = performance.now();
-    const connectorId = await requireCurrentConnectorId();
+    const connectorId = await resolveCurrentConnectorId();
     const createResponse = await api.post(
       "/v1/branch/create",
       {
@@ -529,7 +648,18 @@ async function createAction(name, options) {
       }
     }
     if (!apiBranch) {
-      console.error("\u2717 Branch created but could not fetch details");
+      const message = "Branch created but could not fetch details";
+      trackEvent("CLI: branch create failed", {
+        reason: "create_succeeded_but_details_missing",
+        output_mode: mode
+      });
+      if (mode === "json") {
+        process.stdout.write(
+          renderBranchJsonError("create_succeeded_but_details_missing", message)
+        );
+        process.exit(1);
+      }
+      console.error(`\u2717 ${message}`);
       process.exit(1);
     }
     const branch = {
@@ -542,6 +672,20 @@ async function createAction(name, options) {
       created_at: apiBranch.created_at,
       last_branch_activity: apiBranch.last_branch_activity
     };
+    const url = resolvePrintableUrl(branch);
+    if (url === null) {
+      const message = `Branch '${name}' created but no URL returned`;
+      trackEvent("CLI: branch create failed", {
+        reason: "branch_url_missing",
+        output_mode: mode
+      });
+      if (mode === "json") {
+        process.stdout.write(renderBranchJsonError("branch_url_missing", message));
+        process.exit(1);
+      }
+      console.error(`\u2717 ${message}`);
+      process.exit(1);
+    }
     const cached = getCacheEntry("branches");
     const cachedBranches = cached?.data || [];
     cachedBranches.push(branch);
@@ -551,25 +695,57 @@ async function createAction(name, options) {
     trackEvent("CLI: branch create succeeded", {
       service_type: options.service,
       duration_seconds: parseFloat(elapsed),
-      warning_type: warning?.type
+      warning_type: warning?.type,
+      output_mode: mode
     });
-    console.log(`\u2713 Branch '${name}' created and checked out in ${elapsed}s`);
-    if (branch.branch_url) {
-      console.log(`
-${branch.branch_url}`);
+    if (mode === "json") {
+      const payload = buildBranchJson({
+        branch,
+        warning: warning ?? null,
+        currentBranchName: name
+      });
+      process.stdout.write(renderBranchJson(payload));
+      return;
+    }
+    if (mode === "print-url") {
+      process.stdout.write(url + "\n");
+      return;
     }
+    console.log(`\u2713 Branch '${name}' created and checked out in ${elapsed}s`);
+    console.log(`
+${url}`);
     if (warning) {
       console.log(`
 ! ${warning.message}`);
     }
   } catch (err) {
+    if (err instanceof CurrentConnectorSelectionError) {
+      trackEvent("CLI: branch create failed", { reason: err.code, output_mode: mode });
+      if (mode === "json") {
+        process.stdout.write(renderBranchJsonError(err.code, err.message));
+        process.exit(1);
+      }
+      printCurrentConnectorSelectionError(err);
+      process.exit(1);
+    }
     if (isNetworkError(err)) {
-      trackEvent("CLI: branch create failed", { reason: "offline" });
+      trackEvent("CLI: branch create failed", { reason: "offline", output_mode: mode });
+      if (mode === "json") {
+        process.stdout.write(
+          renderBranchJsonError("offline", "Cannot create branch while offline")
+        );
+        process.exit(1);
+      }
       console.error("\u2717 Cannot create branch while offline");
       process.exit(1);
     }
-    trackEvent("CLI: branch create failed", { reason: "api_error" });
-    console.error("\u2717 Failed:", err instanceof Error ? err.message : err);
+    trackEvent("CLI: branch create failed", { reason: "api_error", output_mode: mode });
+    const message = err instanceof Error ? err.message : String(err);
+    if (mode === "json") {
+      process.stdout.write(renderBranchJsonError("api_error", message));
+      process.exit(1);
+    }
+    console.error("\u2717 Failed:", message);
     process.exit(1);
   }
 }
@@ -650,9 +826,28 @@ async function listAction() {
 }
 
 // src/commands/branch/info.ts
-function infoAction(name) {
+function infoAction(name, options = {}) {
+  const modeResolution = resolveOutputMode(options);
+  if (modeResolution.error) {
+    console.error(`\u2717 ${modeResolution.error}`);
+    process.exit(2);
+  }
+  const mode = modeResolution.mode;
   const branchName = name || getCurrentBranch();
   if (!branchName) {
+    if (mode === "json") {
+      process.stdout.write(
+        renderBranchJsonError(
+          "no_current_branch",
+          "No branch specified and no current branch set"
+        )
+      );
+      process.exit(1);
+    }
+    if (mode === "print-url") {
+      console.error("\u2717 No branch specified and no current branch set");
+      process.exit(1);
+    }
     console.error("\u2717 No branch specified and no current branch set");
     console.log("  Run: ardent branch switch <name> or specify a branch name");
     return;
@@ -660,10 +855,52 @@ function infoAction(name) {
   const cached = getCacheEntry("branches");
   const branch = cached?.data.find((cachedBranch) => cachedBranch.name === branchName);
   if (!branch) {
-    console.error(`\u2717 Branch "${branchName}" not found`);
+    const message = `Branch "${branchName}" not found`;
+    if (mode === "json") {
+      process.stdout.write(renderBranchJsonError("not_found", message));
+      process.exit(1);
+    }
+    if (mode === "print-url") {
+      console.error(`\u2717 ${message}`);
+      process.exit(1);
+    }
+    console.error(`\u2717 ${message}`);
     console.log("  Run: ardent branch list");
     return;
   }
+  if (mode === "json" || mode === "print-url") {
+    const url = resolvePrintableUrl(branch);
+    if (url === null) {
+      const message = `No URL recorded for branch "${branch.name}"`;
+      trackEvent("CLI: branch info failed", {
+        reason: "branch_url_missing",
+        output_mode: mode
+      });
+      if (mode === "json") {
+        process.stdout.write(renderBranchJsonError("branch_url_missing", message));
+        process.exit(1);
+      }
+      console.error(`\u2717 ${message}`);
+      process.exit(1);
+    }
+  }
+  trackEvent("CLI: branch info", { output_mode: mode });
+  if (mode === "json") {
+    const payload = buildBranchJson({
+      branch,
+      currentBranchName: getCurrentBranch()
+    });
+    process.stdout.write(renderBranchJson(payload));
+    return;
+  }
+  if (mode === "print-url") {
+    const url = resolvePrintableUrl(branch);
+    if (url === null) {
+      throw new Error("Branch URL disappeared after validation");
+    }
+    process.stdout.write(url + "\n");
+    return;
+  }
   const current = getCurrentBranch();
   const marker = branch.name === current ? " (current)" : "";
   console.log(`Branch: ${branch.name}${marker}
@@ -675,7 +912,6 @@ function infoAction(name) {
     console.log(`
   URL: ${branch.branch_url}`);
   }
-  trackEvent("CLI: branch info");
 }
 
 // src/commands/branch/delete.ts
@@ -770,9 +1006,9 @@ ${yellow}To view the current state of a branch:${reset2} \`ardent branch info <n
 
 // src/commands/branch/index.ts
 var branchCommand = new Command("branch").description("Manage database branches");
-branchCommand.command("create <name>").description("Create a new database branch").option("-s, --service <type>", "Service type", "postgres").action(createAction);
+branchCommand.command("create <name>").description("Create a new database branch").option("-s, --service <type>", "Service type", "postgres").option("--format <format>", "Output format for CI/agents (currently: json)").option("--print-url", "Print only the branch URL (one line, no other output)").action(createAction);
 branchCommand.command("list").description("List your branches").action(listAction);
-branchCommand.command("info [name]").description("Show branch details (defaults to current branch)").action(infoAction);
+branchCommand.command("info [name]").description("Show branch details (defaults to current branch)").option("--format <format>", "Output format for CI/agents (currently: json)").option("--print-url", "Print only the branch URL (one line, no other output)").action(infoAction);
 branchCommand.command("delete <name>").description("Delete a branch").action(deleteAction);
 branchCommand.command("switch <name>").description("Switch to a different branch").action(switchAction);
 branchCommand.command("diff [name]", { hidden: true }).description("(removed) Show changes on a branch").action(diffAction);
@@ -1786,6 +2022,9 @@ async function createAction2(type, url, options) {
       if (parsed.ssl_mode !== void 0) {
         connectionDetails.ssl_mode = parsed.ssl_mode;
       }
+      if (parsed.database !== void 0) {
+        connectionDetails.database = parsed.database;
+      }
       createPayload = {
         name: connectorName,
         service_name: "postgresql",
@@ -4632,14 +4871,14 @@ function logoutAction() {
 
 // src/commands/auth/status.ts
 function statusAction() {
-  const token = getConfig("token");
+  const token = getToken();
   if (!token) {
     trackEvent("CLI: auth status", { authenticated: false });
     console.log("\u2717 Not authenticated");
     console.log("  Run: ardent login");
     return;
   }
-  const user = getConfig("user");
+  const user = getConfig("token") ? getConfig("user") : void 0;
   console.log("\u2713 Authenticated");
   if (user?.full_name) {
     console.log(`  Account: ${user.full_name}`);
@@ -4658,7 +4897,12 @@ function statusAction() {
 }
 
 // src/commands/auth/index.ts
-var loginCommand = new Command7("login").description("Login to Ardent").option("-t, --token <token>", "API token (skip browser login)").action(loginAction);
+var loginCommand = new Command7("login").description(
+  "Login to Ardent. Defaults to GitHub OAuth in the browser; pass --token for headless auth, or set the ARDENT_TOKEN env var to skip 'ardent login' entirely."
+).option(
+  "-t, --token <token>",
+  "API token for headless auth (skip browser login). For repeat headless use, prefer the ARDENT_TOKEN env var."
+).action(loginAction);
 var logoutCommand = new Command7("logout").description("Logout from Ardent").action(logoutAction);
 var statusCommand = new Command7("status").description("Show status").action(statusAction);
 
@@ -4744,6 +4988,7 @@ USAGE
 
 AUTHENTICATION
   login                  Login via browser (GitHub OAuth)
+  login --token <token>  Login with an API token (headless, no browser)
   logout                 Clear stored credentials
   status                 Check authentication status
 
@@ -4785,12 +5030,29 @@ OPTIONS
   --help                 Show help for any command
   --version              Show CLI version
 
+ENVIRONMENT
+  ARDENT_TOKEN           API token used for every request. When set, no
+                         'ardent login' is needed \u2014 ideal for CI and other
+                         headless contexts. Generate one in the web app
+                         under Settings > API Keys.
+  ARDENT_API_URL         Override the API endpoint
+                         (default: https://api.tryardent.com).
+
 EXAMPLES
   ardent login
   ardent connector create postgresql postgresql://user:password@your-db-host.com:5432/database
   ardent branch create my-feature
   ardent branch switch my-feature
   ardent org members
+
+  # Headless / CI (GitHub Actions)
+  #   env:
+  #     ARDENT_TOKEN: \${{ secrets.ARDENT_TOKEN }}
+  #   run: |
+  #     BRANCH="pr-\${{ github.event.number }}-\${{ github.run_id }}"
+  #     ardent branch create "$BRANCH"
+  #     # ... run your migration / tests against the branch ...
+  #     ardent branch delete "$BRANCH"
 `;
 var program = new Command8();
 program.name("ardent").description("CLI for Ardent database branching").version(CLI_VERSION).configureHelp({
@@ -4825,5 +5087,7 @@ if (args.length === 0) {
   program.help();
 }
 getAnonymousId();
-checkForUpdate(CLI_VERSION);
+if (!isMachineReadableBranchInvocation(args)) {
+  checkForUpdate(CLI_VERSION);
+}
 program.parse();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ardent-cli",
-  "version": "0.0.42",
+  "version": "0.0.44",
   "description": "Git for Data infrastructure",
   "type": "module",
   "bin": {