@tinybirdco/sdk 0.0.13 → 0.0.14

package/src/cli/commands/preview.test.ts

@@ -0,0 +1,42 @@
+import { describe, it, expect, beforeEach, vi } from "vitest";
+import { generatePreviewBranchName } from "./preview.js";
+
+describe("Preview command", () => {
+  describe("generatePreviewBranchName", () => {
+    beforeEach(() => {
+      vi.useFakeTimers();
+      vi.setSystemTime(new Date("2024-02-06T12:00:00Z"));
+    });
+
+    it("generates name with branch and timestamp", () => {
+      const result = generatePreviewBranchName("feature-branch");
+      expect(result).toBe("tmp_ci_feature_branch_1707220800");
+    });
+
+    it("sanitizes branch name with slashes", () => {
+      const result = generatePreviewBranchName("feature/add-login");
+      expect(result).toBe("tmp_ci_feature_add_login_1707220800");
+    });
+
+    it("sanitizes branch name with dots", () => {
+      const result = generatePreviewBranchName("release.1.0");
+      expect(result).toBe("tmp_ci_release_1_0_1707220800");
+    });
+
+    it("handles complex branch names", () => {
+      const result = generatePreviewBranchName("feature/JIRA-123/add-user-auth");
+      expect(result).toBe("tmp_ci_feature_JIRA_123_add_user_auth_1707220800");
+    });
+
+    it("uses 'unknown' when branch is null", () => {
+      const result = generatePreviewBranchName(null);
+      expect(result).toBe("tmp_ci_unknown_1707220800");
+    });
+
+    it("uses unix timestamp in seconds", () => {
+      // 1707220800 is 2024-02-06T12:00:00Z in seconds
+      const result = generatePreviewBranchName("test");
+      expect(result).toMatch(/_1707220800$/);
+    });
+  });
+});

package/src/cli/commands/preview.ts

@@ -0,0 +1,313 @@
+/**
+ * Preview command - creates ephemeral preview branch and deploys resources
+ */
+
+import { loadConfig, LOCAL_BASE_URL, type ResolvedConfig, type DevMode } from "../config.js";
+import { buildFromInclude, type BuildFromIncludeResult } from "../../generator/index.js";
+import { createBranch, type TinybirdBranch } from "../../api/branches.js";
+import { deployToMain } from "../../api/deploy.js";
+import { buildToTinybird } from "../../api/build.js";
+import {
+  getLocalTokens,
+  getOrCreateLocalWorkspace,
+  LocalNotRunningError,
+} from "../../api/local.js";
+import { sanitizeBranchName, getCurrentGitBranch } from "../git.js";
+import type { BuildApiResult } from "../../api/build.js";
+
+/**
+ * Preview command options
+ */
+export interface PreviewCommandOptions {
+  /** Working directory (defaults to cwd) */
+  cwd?: string;
+  /** Skip pushing to API (just generate) */
+  dryRun?: boolean;
+  /** Validate deploy with Tinybird API without applying */
+  check?: boolean;
+  /** Override preview branch name */
+  name?: string;
+  /** Override the devMode from config */
+  devModeOverride?: DevMode;
+}
+
+/**
+ * Preview command result
+ */
+export interface PreviewCommandResult {
+  /** Whether the preview was successful */
+  success: boolean;
+  /** Branch information */
+  branch?: {
+    name: string;
+    id: string;
+    token: string;
+    url: string;
+    created_at: string;
+  };
+  /** Build statistics */
+  build?: {
+    datasourceCount: number;
+    pipeCount: number;
+  };
+  /** Deploy result */
+  deploy?: {
+    result: string;
+  };
+  /** Error message if failed */
+  error?: string;
+  /** Duration in milliseconds */
+  durationMs: number;
+}
+
+/**
+ * Generate preview branch name with format: tmp_ci_${branch}_${timestamp}
+ *
+ * @param gitBranch - Current git branch name (or null)
+ * @returns Preview branch name
+ */
+export function generatePreviewBranchName(gitBranch: string | null): string {
+  const timestamp = Math.floor(Date.now() / 1000);
+  const branchPart = gitBranch ? sanitizeBranchName(gitBranch) : "unknown";
+  return `tmp_ci_${branchPart}_${timestamp}`;
+}
+
+/**
+ * Run the preview command
+ *
+ * Creates an ephemeral preview branch and deploys resources to it.
+ * Preview branches are not cached and are meant for CI/testing.
+ *
+ * @param options - Preview options
+ * @returns Preview command result
+ */
+export async function runPreview(options: PreviewCommandOptions = {}): Promise<PreviewCommandResult> {
+  const startTime = Date.now();
+  const cwd = options.cwd ?? process.cwd();
+
+  // Load config
+  let config: ResolvedConfig;
+  try {
+    config = loadConfig(cwd);
+  } catch (error) {
+    return {
+      success: false,
+      error: (error as Error).message,
+      durationMs: Date.now() - startTime,
+    };
+  }
+
+  // Get current git branch and generate preview branch name
+  const gitBranch = getCurrentGitBranch();
+  const previewBranchName = options.name ?? generatePreviewBranchName(gitBranch);
+
+  // Build resources from include paths
+  let buildResult: BuildFromIncludeResult;
+  try {
+    buildResult = await buildFromInclude({
+      includePaths: config.include,
+      cwd: config.cwd,
+    });
+  } catch (error) {
+    return {
+      success: false,
+      error: `Build failed: ${(error as Error).message}`,
+      durationMs: Date.now() - startTime,
+    };
+  }
+
+  const buildStats = {
+    datasourceCount: buildResult.stats.datasourceCount,
+    pipeCount: buildResult.stats.pipeCount,
+  };
+
+  // If dry run, return without creating branch or deploying
+  if (options.dryRun) {
+    return {
+      success: true,
+      branch: {
+        name: previewBranchName,
+        id: "(dry-run)",
+        token: "(dry-run)",
+        url: config.baseUrl,
+        created_at: new Date().toISOString(),
+      },
+      build: buildStats,
+      durationMs: Date.now() - startTime,
+    };
+  }
+
+  const debug = !!process.env.TINYBIRD_DEBUG;
+  const devMode = options.devModeOverride ?? config.devMode;
+
+  if (debug) {
+    console.log(`[debug] devMode: ${devMode}`);
+    console.log(`[debug] previewBranchName: ${previewBranchName}`);
+  }
+
+  // Handle local mode
+  if (devMode === "local") {
+    try {
+      if (debug) {
+        console.log(`[debug] Getting local tokens from ${LOCAL_BASE_URL}/tokens`);
+      }
+
+      const localTokens = await getLocalTokens();
+
+      // Create workspace with preview branch name
+      if (debug) {
+        console.log(`[debug] Creating local workspace: ${previewBranchName}`);
+      }
+
+      const { workspace, wasCreated } = await getOrCreateLocalWorkspace(localTokens, previewBranchName);
+      if (debug) {
+        console.log(`[debug] Workspace ${wasCreated ? "created" : "found"}: ${workspace.name}`);
+      }
+
+      // Use /v1/build for local (no deploy endpoint in local)
+      const deployResult = await buildToTinybird(
+        {
+          baseUrl: LOCAL_BASE_URL,
+          token: workspace.token,
+        },
+        buildResult.resources
+      );
+
+      if (!deployResult.success) {
+        return {
+          success: false,
+          branch: {
+            name: previewBranchName,
+            id: workspace.id,
+            token: workspace.token,
+            url: LOCAL_BASE_URL,
+            created_at: new Date().toISOString(),
+          },
+          build: buildStats,
+          error: deployResult.error,
+          durationMs: Date.now() - startTime,
+        };
+      }
+
+      return {
+        success: true,
+        branch: {
+          name: previewBranchName,
+          id: workspace.id,
+          token: workspace.token,
+          url: LOCAL_BASE_URL,
+          created_at: new Date().toISOString(),
+        },
+        build: buildStats,
+        deploy: {
+          result: deployResult.result,
+        },
+        durationMs: Date.now() - startTime,
+      };
+    } catch (error) {
+      if (error instanceof LocalNotRunningError) {
+        return {
+          success: false,
+          error: error.message,
+          durationMs: Date.now() - startTime,
+        };
+      }
+      return {
+        success: false,
+        error: `Local preview failed: ${(error as Error).message}`,
+        durationMs: Date.now() - startTime,
+      };
+    }
+  }
+
+  // Cloud mode - create branch and deploy using /v1/deploy
+  let branch: TinybirdBranch;
+  try {
+    if (debug) {
+      console.log(`[debug] Creating preview branch: ${previewBranchName}`);
+    }
+
+    branch = await createBranch(
+      { baseUrl: config.baseUrl, token: config.token },
+      previewBranchName
+    );
+
+    if (debug) {
+      console.log(`[debug] Branch created: ${branch.name} (${branch.id})`);
+    }
+  } catch (error) {
+    return {
+      success: false,
+      error: `Failed to create preview branch: ${(error as Error).message}`,
+      durationMs: Date.now() - startTime,
+    };
+  }
+
+  if (!branch.token) {
+    return {
+      success: false,
+      error: `Preview branch created but no token returned`,
+      durationMs: Date.now() - startTime,
+    };
+  }
+
+  // Deploy to branch using /v1/deploy (production-like experience)
+  let deployResult: BuildApiResult;
+  try {
+    if (debug) {
+      console.log(`[debug] Deploying to preview branch using branch token`);
+    }
+
+    deployResult = await deployToMain(
+      { baseUrl: config.baseUrl, token: branch.token },
+      buildResult.resources,
+      { check: options.check, allowDestructiveOperations: true }
+    );
+  } catch (error) {
+    return {
+      success: false,
+      branch: {
+        name: branch.name,
+        id: branch.id,
+        token: branch.token,
+        url: config.baseUrl,
+        created_at: branch.created_at,
+      },
+      build: buildStats,
+      error: `Deploy failed: ${(error as Error).message}`,
+      durationMs: Date.now() - startTime,
+    };
+  }
+
+  if (!deployResult.success) {
+    return {
+      success: false,
+      branch: {
+        name: branch.name,
+        id: branch.id,
+        token: branch.token,
+        url: config.baseUrl,
+        created_at: branch.created_at,
+      },
+      build: buildStats,
+      error: deployResult.error,
+      durationMs: Date.now() - startTime,
+    };
+  }
+
+  return {
+    success: true,
+    branch: {
+      name: branch.name,
+      id: branch.id,
+      token: branch.token,
+      url: config.baseUrl,
+      created_at: branch.created_at,
+    },
+    build: buildStats,
+    deploy: {
+      result: deployResult.result,
+    },
+    durationMs: Date.now() - startTime,
+  };
+}

package/src/cli/index.ts

@@ -14,9 +14,11 @@ import { readFileSync } from "node:fs";
 import { fileURLToPath } from "node:url";
 import { dirname, join, resolve } from "node:path";
 import { Command } from "commander";
+import pc from "picocolors";
 import { runInit } from "./commands/init.js";
 import { runBuild } from "./commands/build.js";
 import { runDeploy } from "./commands/deploy.js";
+import { runPreview } from "./commands/preview.js";
 import { runDev } from "./commands/dev.js";
 import { runLogin } from "./commands/login.js";
 import {
@@ -31,7 +33,7 @@ import {
   hasTinybirdSdkDependency,
 } from "./utils/package-manager.js";
 import type { DevMode } from "./config.js";
-import { output } from "./output.js";
+import { output, type ResourceChange } from "./output.js";
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const packageJson = JSON.parse(
@@ -229,32 +231,34 @@ function createCli(): Command {
         if (deploy.result === "no_changes") {
           output.showNoChanges();
         } else {
-          // Show datasource changes
+          // Collect all changes for table display
+          const changes: ResourceChange[] = [];
+
           if (deploy.datasources) {
             for (const name of deploy.datasources.created) {
-              output.showResourceChange(`${name}.datasource`, "created");
+              changes.push({ status: "new", name, type: "datasource" });
             }
             for (const name of deploy.datasources.changed) {
-              output.showResourceChange(`${name}.datasource`, "changed");
+              changes.push({ status: "modified", name, type: "datasource" });
             }
             for (const name of deploy.datasources.deleted) {
-              output.showResourceChange(`${name}.datasource`, "deleted");
+              changes.push({ status: "deleted", name, type: "datasource" });
             }
           }
 
-          // Show pipe changes
           if (deploy.pipes) {
             for (const name of deploy.pipes.created) {
-              output.showResourceChange(`${name}.pipe`, "created");
+              changes.push({ status: "new", name, type: "pipe" });
             }
             for (const name of deploy.pipes.changed) {
-              output.showResourceChange(`${name}.pipe`, "changed");
+              changes.push({ status: "modified", name, type: "pipe" });
             }
             for (const name of deploy.pipes.deleted) {
-              output.showResourceChange(`${name}.pipe`, "deleted");
+              changes.push({ status: "deleted", name, type: "pipe" });
             }
           }
 
+          output.showChangesTable(changes);
           output.showBuildSuccess(result.durationMs);
         }
       }
@@ -277,6 +281,48 @@ function createCli(): Command {
       const result = await runDeploy({
         dryRun: options.dryRun,
         check: options.check,
+        callbacks: {
+          onChanges: (deployChanges) => {
+            // Show changes table immediately after deployment is created
+            const changes: ResourceChange[] = [];
+
+            for (const name of deployChanges.datasources.created) {
+              changes.push({ status: "new", name, type: "datasource" });
+            }
+            for (const name of deployChanges.datasources.changed) {
+              changes.push({ status: "modified", name, type: "datasource" });
+            }
+            for (const name of deployChanges.datasources.deleted) {
+              changes.push({ status: "deleted", name, type: "datasource" });
+            }
+
+            for (const name of deployChanges.pipes.created) {
+              changes.push({ status: "new", name, type: "pipe" });
+            }
+            for (const name of deployChanges.pipes.changed) {
+              changes.push({ status: "modified", name, type: "pipe" });
+            }
+            for (const name of deployChanges.pipes.deleted) {
+              changes.push({ status: "deleted", name, type: "pipe" });
+            }
+
+            for (const name of deployChanges.connections.created) {
+              changes.push({ status: "new", name, type: "connection" });
+            }
+            for (const name of deployChanges.connections.changed) {
+              changes.push({ status: "modified", name, type: "connection" });
+            }
+            for (const name of deployChanges.connections.deleted) {
+              changes.push({ status: "deleted", name, type: "connection" });
+            }
+
+            output.showChangesTable(changes);
+          },
+          onWaitingForReady: () => output.showWaitingForDeployment(),
+          onDeploymentReady: () => output.showDeploymentReady(),
+          onDeploymentLive: (id) => output.showDeploymentLive(id),
+          onValidating: () => output.showValidatingDeployment(),
+        },
       });
 
       const { build, deploy } = result;
@@ -288,7 +334,7 @@ function createCli(): Command {
         } else if (result.error) {
           output.error(result.error);
         }
-        output.showBuildFailure();
+        output.showDeployFailure();
         process.exit(1);
       }
 
@@ -309,43 +355,107 @@ function createCli(): Command {
             console.log(pipe.content);
           });
         }
-        output.showBuildSuccess(result.durationMs);
+        output.showDeploySuccess(result.durationMs);
       } else if (options.check) {
         console.log("\n[Check] Resources validated with Tinybird API");
-        output.showBuildSuccess(result.durationMs);
+        output.showDeploySuccess(result.durationMs);
       } else if (deploy) {
         if (deploy.result === "no_changes") {
           output.showNoChanges();
         } else {
-          // Show datasource changes
-          if (deploy.datasources) {
-            for (const name of deploy.datasources.created) {
-              output.showResourceChange(`${name}.datasource`, "created");
-            }
-            for (const name of deploy.datasources.changed) {
-              output.showResourceChange(`${name}.datasource`, "changed");
-            }
-            for (const name of deploy.datasources.deleted) {
-              output.showResourceChange(`${name}.datasource`, "deleted");
-            }
-          }
+          // Changes table was already shown via onChanges callback
+          output.showDeploySuccess(result.durationMs);
+        }
+      }
+    });
 
-          // Show pipe changes
-          if (deploy.pipes) {
-            for (const name of deploy.pipes.created) {
-              output.showResourceChange(`${name}.pipe`, "created");
-            }
-            for (const name of deploy.pipes.changed) {
-              output.showResourceChange(`${name}.pipe`, "changed");
-            }
-            for (const name of deploy.pipes.deleted) {
-              output.showResourceChange(`${name}.pipe`, "deleted");
-            }
-          }
+  // Preview command
+  program
+    .command("preview")
+    .description("Create a preview branch and deploy resources (for CI/testing)")
+    .option("--dry-run", "Generate without creating branch or deploying")
+    .option("--check", "Validate deploy with Tinybird API without applying")
+    .option("--debug", "Show debug output including API requests/responses")
+    .option("--json", "Output JSON instead of human-readable format")
+    .option("-n, --name <name>", "Override preview branch name")
+    .option("--local", "Use local Tinybird container")
+    .action(async (options) => {
+      if (options.debug) {
+        process.env.TINYBIRD_DEBUG = "1";
+      }
 
-          output.showBuildSuccess(result.durationMs);
+      // Determine devMode override
+      let devModeOverride: DevMode | undefined;
+      if (options.local) {
+        devModeOverride = "local";
+      }
+
+      if (!options.json) {
+        const modeLabel = devModeOverride === "local" ? " (local)" : "";
+        console.log(`Creating preview branch${modeLabel}...\n`);
+      }
+
+      const result = await runPreview({
+        dryRun: options.dryRun,
+        check: options.check,
+        name: options.name,
+        devModeOverride,
+      });
+
+      // JSON output mode
+      if (options.json) {
+        console.log(JSON.stringify(result, null, 2));
+        if (!result.success) {
+          process.exit(1);
+        }
+        return;
+      }
+
+      // Human-readable output mode
+      if (!result.success) {
+        // Parse error message for individual errors (one per line)
+        const errorLines = result.error?.split("\n") ?? ["Unknown error"];
+        for (const line of errorLines) {
+          console.log(pc.red(`- ${line}`));
+        }
+        console.log("");
+        console.log(pc.red(`✗ Preview failed`));
+        process.exit(1);
+      }
+
+      // Success output
+      const durationSec = (result.durationMs / 1000).toFixed(1);
+      if (result.branch) {
+        if (options.dryRun) {
+          console.log(pc.green(`✓ Preview branch: ${result.branch.name}`));
+          console.log(pc.dim("  (dry run - branch not created)"));
+        } else {
+          console.log(pc.green(`✓ Preview branch: ${result.branch.name}`));
+          console.log(pc.dim(`  ID: ${result.branch.id}`));
+          console.log(pc.dim(`  (use --json to get branch token)`));
+        }
+      }
+
+      if (result.build) {
+        console.log(
+          pc.green(`✓ Generated ${result.build.datasourceCount} datasource(s), ${result.build.pipeCount} pipe(s)`)
+        );
+      }
+
+      if (options.dryRun) {
+        console.log(pc.dim("\n[Dry run] Resources not deployed to API"));
+      } else if (options.check) {
+        console.log(pc.green("\n✓ Resources validated with Tinybird API"));
+      } else if (result.deploy) {
+        if (result.deploy.result === "no_changes") {
+          console.log(pc.green("✓ No changes detected - already up to date"));
+        } else {
+          console.log(pc.green("✓ Deployed to preview branch"));
         }
       }
+
+      console.log("");
+      console.log(pc.green(`✓ Preview completed in ${durationSec}s`));
     });
 
   // Dev command