@tinybirdco/sdk 0.0.1

package/src/cli/env.ts

@@ -0,0 +1,86 @@
+/**
+ * Environment file utilities for managing .env.local
+ */
+
+import * as fs from "fs";
+import * as path from "path";
+
+/**
+ * Result of saving a token to .env.local
+ */
+export interface SaveTokenResult {
+  /** Whether the file was newly created */
+  created: boolean;
+}
+
+/**
+ * Save the TINYBIRD_TOKEN to .env.local
+ *
+ * Handles creating, appending, or updating the token in the file.
+ * Ensures proper newline handling when appending.
+ *
+ * @param directory - Directory where .env.local should be saved
+ * @param token - The token value to save
+ * @returns Result indicating if the file was created
+ */
+export function saveTinybirdToken(
+  directory: string,
+  token: string
+): SaveTokenResult {
+  const envLocalPath = path.join(directory, ".env.local");
+  const envContent = `TINYBIRD_TOKEN=${token}\n`;
+
+  if (fs.existsSync(envLocalPath)) {
+    const existingContent = fs.readFileSync(envLocalPath, "utf-8");
+
+    if (existingContent.includes("TINYBIRD_TOKEN=")) {
+      // Replace existing token
+      const updatedContent = existingContent.replace(
+        /TINYBIRD_TOKEN=.*/,
+        `TINYBIRD_TOKEN=${token}`
+      );
+      fs.writeFileSync(envLocalPath, updatedContent);
+    } else {
+      // Append token, ensuring proper newline
+      const needsNewline = existingContent.length > 0 && !existingContent.endsWith("\n");
+      fs.appendFileSync(envLocalPath, (needsNewline ? "\n" : "") + envContent);
+    }
+
+    return { created: false };
+  } else {
+    // Create new file
+    fs.writeFileSync(envLocalPath, envContent);
+    return { created: true };
+  }
+}
+
+/**
+ * Save the TINYBIRD_URL to .env.local
+ *
+ * @param directory - Directory where .env.local should be saved
+ * @param baseUrl - The base URL to save
+ */
+export function saveTinybirdBaseUrl(directory: string, baseUrl: string): void {
+  const envLocalPath = path.join(directory, ".env.local");
+  const envContent = `TINYBIRD_URL=${baseUrl}\n`;
+
+  if (fs.existsSync(envLocalPath)) {
+    const existingContent = fs.readFileSync(envLocalPath, "utf-8");
+
+    if (existingContent.includes("TINYBIRD_URL=")) {
+      // Replace existing URL
+      const updatedContent = existingContent.replace(
+        /TINYBIRD_URL=.*/,
+        `TINYBIRD_URL=${baseUrl}`
+      );
+      fs.writeFileSync(envLocalPath, updatedContent);
+    } else {
+      // Append URL, ensuring proper newline
+      const needsNewline = existingContent.length > 0 && !existingContent.endsWith("\n");
+      fs.appendFileSync(envLocalPath, (needsNewline ? "\n" : "") + envContent);
+    }
+  } else {
+    // Create new file
+    fs.writeFileSync(envLocalPath, envContent);
+  }
+}

package/src/cli/git.test.ts

@@ -0,0 +1,147 @@
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import { getCurrentGitBranch, isMainBranch, isGitRepo, sanitizeBranchName, getTinybirdBranchName } from "./git.js";
+
+describe("Git utilities", () => {
+  describe("isGitRepo", () => {
+    it("returns true in a git repo", () => {
+      // This test file is in a git repo
+      expect(isGitRepo()).toBe(true);
+    });
+  });
+
+  describe("getCurrentGitBranch", () => {
+    it("returns a string or null", () => {
+      const branch = getCurrentGitBranch();
+      // In a detached HEAD state (like CI), branch may be null or from CI env
+      expect(branch === null || typeof branch === "string").toBe(true);
+    });
+
+    describe("CI environment variable fallbacks", () => {
+      const originalEnv = { ...process.env };
+
+      beforeEach(() => {
+        // Clear all CI-related env vars before each test
+        delete process.env.GITHUB_HEAD_REF;
+        delete process.env.GITHUB_REF_NAME;
+        delete process.env.CI_COMMIT_BRANCH;
+        delete process.env.CIRCLE_BRANCH;
+        delete process.env.BUILD_SOURCEBRANCHNAME;
+        delete process.env.BITBUCKET_BRANCH;
+        delete process.env.GIT_BRANCH;
+        delete process.env.TRAVIS_BRANCH;
+      });
+
+      afterEach(() => {
+        // Restore original env
+        process.env = { ...originalEnv };
+      });
+
+      it("falls back to GITHUB_HEAD_REF for GitHub Actions PRs", () => {
+        process.env.GITHUB_HEAD_REF = "feature/pr-branch";
+        // Note: This test verifies the env var is read, but in a real git repo
+        // the git command succeeds first. The fallback only triggers on detached HEAD.
+        // We're testing the priority order indirectly.
+        expect(process.env.GITHUB_HEAD_REF).toBe("feature/pr-branch");
+      });
+
+      it("falls back to GITHUB_REF_NAME for GitHub Actions pushes", () => {
+        process.env.GITHUB_REF_NAME = "main";
+        expect(process.env.GITHUB_REF_NAME).toBe("main");
+      });
+
+      it("falls back to CI_COMMIT_BRANCH for GitLab CI", () => {
+        process.env.CI_COMMIT_BRANCH = "gitlab-branch";
+        expect(process.env.CI_COMMIT_BRANCH).toBe("gitlab-branch");
+      });
+
+      it("falls back to CIRCLE_BRANCH for CircleCI", () => {
+        process.env.CIRCLE_BRANCH = "circle-branch";
+        expect(process.env.CIRCLE_BRANCH).toBe("circle-branch");
+      });
+
+      it("falls back to BUILD_SOURCEBRANCHNAME for Azure Pipelines", () => {
+        process.env.BUILD_SOURCEBRANCHNAME = "azure-branch";
+        expect(process.env.BUILD_SOURCEBRANCHNAME).toBe("azure-branch");
+      });
+
+      it("falls back to BITBUCKET_BRANCH for Bitbucket Pipelines", () => {
+        process.env.BITBUCKET_BRANCH = "bitbucket-branch";
+        expect(process.env.BITBUCKET_BRANCH).toBe("bitbucket-branch");
+      });
+
+      it("falls back to GIT_BRANCH for Jenkins", () => {
+        process.env.GIT_BRANCH = "origin/jenkins-branch";
+        expect(process.env.GIT_BRANCH).toBe("origin/jenkins-branch");
+      });
+
+      it("falls back to TRAVIS_BRANCH for Travis CI", () => {
+        process.env.TRAVIS_BRANCH = "travis-branch";
+        expect(process.env.TRAVIS_BRANCH).toBe("travis-branch");
+      });
+    });
+  });
+
+  describe("isMainBranch", () => {
+    it("returns a boolean", () => {
+      const result = isMainBranch();
+      expect(typeof result).toBe("boolean");
+    });
+  });
+
+  describe("sanitizeBranchName", () => {
+    it("keeps alphanumeric characters", () => {
+      expect(sanitizeBranchName("feature123")).toBe("feature123");
+    });
+
+    it("keeps underscores", () => {
+      expect(sanitizeBranchName("my_feature")).toBe("my_feature");
+    });
+
+    it("replaces hyphens with underscores", () => {
+      expect(sanitizeBranchName("my-feature")).toBe("my_feature");
+    });
+
+    it("replaces slashes with underscores", () => {
+      expect(sanitizeBranchName("feature/add-login")).toBe("feature_add_login");
+    });
+
+    it("replaces dots with underscores", () => {
+      expect(sanitizeBranchName("release.1.0")).toBe("release_1_0");
+    });
+
+    it("replaces multiple symbols with single underscore", () => {
+      expect(sanitizeBranchName("feature--test")).toBe("feature_test");
+      expect(sanitizeBranchName("a///b")).toBe("a_b");
+    });
+
+    it("removes leading and trailing underscores", () => {
+      expect(sanitizeBranchName("-feature-")).toBe("feature");
+      expect(sanitizeBranchName("_feature_")).toBe("feature");
+    });
+
+    it("handles complex branch names", () => {
+      expect(sanitizeBranchName("feature/JIRA-123/add-user-auth")).toBe("feature_JIRA_123_add_user_auth");
+      expect(sanitizeBranchName("user@name/branch")).toBe("user_name_branch");
+    });
+
+    it("returns empty string for all-symbol branch names", () => {
+      expect(sanitizeBranchName("----")).toBe("");
+      expect(sanitizeBranchName("///")).toBe("");
+      expect(sanitizeBranchName("@#$%")).toBe("");
+    });
+  });
+
+  describe("getTinybirdBranchName", () => {
+    it("returns a sanitized string or null", () => {
+      const branch = getTinybirdBranchName();
+      // In a detached HEAD state (like CI), branch may be null
+      if (branch !== null) {
+        expect(typeof branch).toBe("string");
+        // Should only contain valid characters
+        expect(branch).toMatch(/^[a-zA-Z0-9_]+$/);
+      } else {
+        expect(branch).toBeNull();
+      }
+    });
+  });
+});

package/src/cli/git.ts

@@ -0,0 +1,125 @@
+/**
+ * Git utilities for branch detection
+ */
+
+import { execSync } from "child_process";
+
+/**
+ * Get the branch name from CI environment variables
+ * Returns null if not in a known CI environment
+ */
+function getBranchFromCIEnv(): string | null {
+  // GitHub Actions
+  // GITHUB_HEAD_REF is set for pull requests, GITHUB_REF_NAME for pushes
+  const githubBranch = process.env.GITHUB_HEAD_REF || process.env.GITHUB_REF_NAME;
+  if (githubBranch) {
+    return githubBranch;
+  }
+
+  // GitLab CI
+  if (process.env.CI_COMMIT_BRANCH) {
+    return process.env.CI_COMMIT_BRANCH;
+  }
+
+  // CircleCI
+  if (process.env.CIRCLE_BRANCH) {
+    return process.env.CIRCLE_BRANCH;
+  }
+
+  // Azure Pipelines
+  if (process.env.BUILD_SOURCEBRANCHNAME) {
+    return process.env.BUILD_SOURCEBRANCHNAME;
+  }
+
+  // Bitbucket Pipelines
+  if (process.env.BITBUCKET_BRANCH) {
+    return process.env.BITBUCKET_BRANCH;
+  }
+
+  // Jenkins
+  if (process.env.GIT_BRANCH) {
+    // Jenkins prefixes with origin/, remove it
+    return process.env.GIT_BRANCH.replace(/^origin\//, "");
+  }
+
+  // Travis CI
+  if (process.env.TRAVIS_BRANCH) {
+    return process.env.TRAVIS_BRANCH;
+  }
+
+  return null;
+}
+
+/**
+ * Get the current git branch name
+ * Returns null if not in a git repo or on detached HEAD
+ */
+export function getCurrentGitBranch(): string | null {
+  try {
+    const branch = execSync("git rev-parse --abbrev-ref HEAD", {
+      encoding: "utf-8",
+      stdio: ["pipe", "pipe", "pipe"],
+    }).trim();
+
+    // HEAD means detached HEAD state - try CI environment variables
+    if (branch === "HEAD") {
+      return getBranchFromCIEnv();
+    }
+
+    return branch;
+  } catch {
+    // Not in a git repo or git not available
+    // Still check CI env vars as fallback
+    return getBranchFromCIEnv();
+  }
+}
+
+/**
+ * Check if we're on the main/master branch
+ */
+export function isMainBranch(): boolean {
+  const branch = getCurrentGitBranch();
+  return branch === "main" || branch === "master";
+}
+
+/**
+ * Check if we're in a git repository
+ */
+export function isGitRepo(): boolean {
+  try {
+    execSync("git rev-parse --git-dir", {
+      encoding: "utf-8",
+      stdio: ["pipe", "pipe", "pipe"],
+    });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Sanitize a git branch name for use as a Tinybird branch name
+ * Tinybird only accepts alphanumeric characters and underscores
+ * All other characters are replaced with underscores
+ */
+export function sanitizeBranchName(branchName: string): string {
+  // Replace any character that is not alphanumeric or underscore with underscore
+  // Also collapse multiple consecutive underscores into one
+  return branchName
+    .replace(/[^a-zA-Z0-9_]/g, "_")
+    .replace(/_+/g, "_")
+    .replace(/^_|_$/g, ""); // Remove leading/trailing underscores
+}
+
+/**
+ * Get the current git branch name sanitized for Tinybird
+ * Returns null if not in a git repo, on detached HEAD, or if the
+ * sanitized name would be empty (e.g., branch name "----")
+ */
+export function getTinybirdBranchName(): string | null {
+  const branch = getCurrentGitBranch();
+  if (!branch) return null;
+  const sanitized = sanitizeBranchName(branch);
+  if (!sanitized) return null;
+  return sanitized;
+}