feat(cli): dev branch support

Let the CLI target a development branch, against the updated server API.

- `trigger dev --branch <branch>` resolves a dev branch (flag or
  TRIGGER_DEV_BRANCH, defaulting to "default") via getDevBranch, upserts
  it on boot, and sends the x-trigger-branch header on requests.
- Per-branch dev lock files so concurrent dev sessions on different
  branches don't evict each other; "default" keeps the dev.lock name.
- New `trigger dev archive` command to archive a dev branch; archive API
  calls now pass the env ("preview" | "development").
- Dev output shows the active branch.

TRI-8726

Author: carderne

docs/management/authentication.mdx

@@ -119,7 +119,7 @@ await envvars.update("proj_1234", "preview", "DATABASE_URL", {
 
   </Tab>
   <Tab title="cURL">
-    To target a specific preview branch, include the `x-trigger-branch` header in your API requests with the branch name as the value:
+    To target a specific preview or development branch, include the `x-trigger-branch` header in your API requests with the branch name as the value:
 
 ```bash
 curl --request PUT \
@@ -137,8 +137,8 @@ curl --request PUT \
 This will set the `DATABASE_URL` environment variable specifically for the `feature-xyz` preview branch.
 
 <Note>
-  The `x-trigger-branch` header is only relevant when working with the `preview` environment (`{env}
-  ` parameter set to `preview`). It has no effect when working with `dev`, `staging`, or `prod`
+  The `x-trigger-branch` header is only relevant when working with the `preview` or `dev` environments (`{env}
+  ` parameter set to `preview` or `development`). It has no effect when working with `staging`, or `prod`
   environments.
 </Note>
 

packages/cli-v3/src/apiClient.ts

@@ -320,7 +320,7 @@ export class CliApiClient {
     );
   }
 
-  async archiveBranch(projectRef: string, branch: string) {
+  async archiveBranch(projectRef: string, env: string, branch: string) {
     if (!this.accessToken) {
       throw new Error("archiveBranch: No access token");
     }
@@ -331,7 +331,7 @@ export class CliApiClient {
       {
         method: "POST",
         headers: this.getHeaders(),
-        body: JSON.stringify({ branch }),
+        body: JSON.stringify({ env, branch }),
       }
     );
   }
@@ -694,6 +694,7 @@ export class CliApiClient {
       headers: {
         Authorization: `Bearer ${this.accessToken}`,
         Accept: "application/json",
+        ...this.getBranchHeader(),
       },
     });
   }
@@ -714,6 +715,7 @@ export class CliApiClient {
           headers: {
             ...init?.headers,
             Authorization: `Bearer ${this.accessToken}`,
+            ...this.getBranchHeader(),
           },
         }),
     });
@@ -766,6 +768,7 @@ export class CliApiClient {
       headers: {
         Authorization: `Bearer ${this.accessToken}`,
         Accept: "application/json",
+        ...this.getBranchHeader(),
       },
       body: JSON.stringify(body),
     });
@@ -783,6 +786,7 @@ export class CliApiClient {
       headers: {
         Authorization: `Bearer ${this.accessToken}`,
         Accept: "application/json",
+        ...this.getBranchHeader(),
       },
       body: JSON.stringify(body),
     });
@@ -802,6 +806,7 @@ export class CliApiClient {
         Authorization: `Bearer ${this.accessToken}`,
         Accept: "application/json",
         "Content-Type": "application/json",
+        ...this.getBranchHeader(),
       },
       body: JSON.stringify(body),
     });
@@ -818,6 +823,7 @@ export class CliApiClient {
         headers: {
           Authorization: `Bearer ${this.accessToken}`,
           Accept: "application/json",
+          ...this.getBranchHeader(),
         },
       }
     );
@@ -837,6 +843,7 @@ export class CliApiClient {
           Authorization: `Bearer ${this.accessToken}`,
           Accept: "application/json",
           "Content-Type": "application/json",
+          ...this.getBranchHeader(),
         },
         body: JSON.stringify(body),
       }
@@ -855,6 +862,7 @@ export class CliApiClient {
         headers: {
           Authorization: `Bearer ${this.accessToken}`,
           Accept: "application/json",
+          ...this.getBranchHeader(),
         },
         //no body at the moment, but we'll probably add things soon
         body: JSON.stringify({}),
@@ -875,6 +883,7 @@ export class CliApiClient {
         headers: {
           Authorization: `Bearer ${this.accessToken}`,
           Accept: "application/json",
+          ...this.getBranchHeader(),
         },
         body: JSON.stringify(body),
       }
@@ -898,4 +907,8 @@ export class CliApiClient {
 
     return headers;
   }
+
+  private getBranchHeader(): Record<string, string> {
+    return this.branch ? { "x-trigger-branch": this.branch } : {};
+  }
 }

packages/cli-v3/src/commands/deploy.ts

@@ -57,8 +57,8 @@ import { getProjectClient, upsertBranch } from "../utilities/session.js";
 import { getTmpDir } from "../utilities/tempDirectories.js";
 import { spinner } from "../utilities/windows.js";
 import { login } from "./login.js";
-import { archivePreviewBranch } from "./preview.js";
 import { updateTriggerPackages } from "./update.js";
+import { archivePreviewBranch } from "./preview.js";
 
 const DeployCommandOptions = CommonCommandOptions.extend({
   dryRun: z.boolean().default(false),

packages/cli-v3/src/commands/dev.ts

@@ -1,8 +1,13 @@
+import { intro } from "@clack/prompts";
+import { resolve } from "node:path";
+import { spinner } from "../utilities/windows.js";
+import { loadConfig } from "../config.js";
+import { verifyDirectory } from "./deploy.js";
 import { ResolvedConfig } from "@trigger.dev/core/v3/build";
 import { Command, Option as CommandOption } from "commander";
 import { z } from "zod";
 import { CliApiClient } from "../apiClient.js";
-import { CommonCommandOptions, commonOptions, wrapCommandAction } from "../cli/common.js";
+import { CommonCommandOptions, commonOptions, handleTelemetry, wrapCommandAction } from "../cli/common.js";
 import { watchConfig } from "../config.js";
 import { DevSessionInstance, startDevSession } from "../dev/devSession.js";
 import { createLockFile } from "../dev/lock.js";
@@ -27,11 +32,22 @@ import { installMcpServer } from "./install-mcp.js";
 import { tryCatch } from "@trigger.dev/core/utils";
 import { VERSION } from "@trigger.dev/core";
 import { initiateSkillsInstallWizard } from "./skills.js";
+import { getDevBranch } from "@trigger.dev/core/v3";
+
+const DevArchiveCommandOptions = CommonCommandOptions.extend({
+  branch: z.string().optional(),
+  config: z.string().optional(),
+  projectRef: z.string().optional(),
+  skipUpdateCheck: z.boolean().default(false),
+});
+
+type DevArchiveCommandOptions = z.infer<typeof DevArchiveCommandOptions>;
 
 const DevCommandOptions = CommonCommandOptions.extend({
   debugOtel: z.boolean().default(false),
   config: z.string().optional(),
   projectRef: z.string().optional(),
+  branch: z.string().optional(),
   skipUpdateCheck: z.boolean().default(false),
   skipPlatformNotifications: z.boolean().default(false),
   envFile: z.string().optional(),
@@ -48,15 +64,45 @@ const DevCommandOptions = CommonCommandOptions.extend({
 export type DevCommandOptions = z.infer<typeof DevCommandOptions>;
 
 export function configureDevCommand(program: Command) {
-  return commonOptions(
-    program
-      .command("dev")
-      .description("Run your Trigger.dev tasks locally")
+  const devBase = program.command("dev").description("Run your Trigger.dev tasks locally");
+
+  commonOptions(
+    devBase
+      .command("archive")
+      .description("Archive a dev branch")
+      .argument("[path]", "The path to the project", ".")
+      .option(
+        "-b, --branch <branch>",
+        "The dev branch to archive. If not provided, we'll detect your local git branch."
+      )
+      .option("--skip-update-check", "Skip checking for @trigger.dev package updates")
+      .option("-c, --config <config file>", "The name of the config file, found at [path]")
+      .option(
+        "-p, --project-ref <project ref>",
+        "The project ref. Required if there is no config file. This will override the project specified in the config file."
+      )
+      .option(
+        "--env-file <env file>",
+        "Path to the .env file to load into the CLI process. Defaults to .env in the project directory."
+      )
+  ).action(async (path, options) => {
+    await handleTelemetry(async () => {
+      await printStandloneInitialBanner(true, options.profile);
+      await devArchiveCommand(path, options);
+    });
+  });
+
+  commonOptions(
+    devBase
       .option("-c, --config <config file>", "The name of the config file")
       .option(
         "-p, --project-ref <project ref>",
         "The project ref. Required if there is no config file."
       )
+      .option(
+        "-b, --branch <branch>",
+        "The dev branch to use. If not provided, we'll use the default branch."
+      )
       .option(
         "--env-file <env file>",
         "Path to the .env file to use for the dev session. Defaults to .env in the project directory."
@@ -164,8 +210,7 @@ export async function devCommand(options: DevCommandOptions) {
       );
     } else {
       logger.log(
-        `${chalkError("X Error:")} You must login first. Use the \`login\` CLI command.\n\n${
-          authorization.error
+        `${chalkError("X Error:")} You must login first. Use the \`login\` CLI command.\n\n${authorization.error
         }`
       );
     }
@@ -198,12 +243,14 @@ async function startDev(options: StartDevOptions) {
       logger.loggerLevel = options.logLevel;
     }
 
+    const apiClient = new CliApiClient(options.login.auth.apiUrl, options.login.auth.accessToken);
+
     const notificationPromise = options.skipPlatformNotifications
       ? undefined
       : fetchPlatformNotification({
-          apiClient: new CliApiClient(options.login.auth.apiUrl, options.login.auth.accessToken),
-          projectRef: options.projectRef,
-        });
+        apiClient,
+        projectRef: options.projectRef,
+      });
 
     await printStandloneInitialBanner(true, options.profile);
 
@@ -215,7 +262,9 @@ async function startDev(options: StartDevOptions) {
       displayedUpdateMessage = await updateTriggerPackages(options.cwd, { ...options }, true, true);
     }
 
-    const removeLockFile = await createLockFile(options.cwd);
+    const branch = getDevBranch({ specified: options.branch });
+
+    const removeLockFile = await createLockFile(options.cwd, branch);
 
     let devInstance: DevSessionInstance | undefined;
 
@@ -246,13 +295,18 @@ async function startDev(options: StartDevOptions) {
 
     logger.debug("Initial config", watcher.config);
 
+    if (branch !== "default") {
+      await apiClient.upsertBranch(watcher.config.project, { branch, env: "development" });
+    }
+
     // eslint-disable-next-line no-inner-declarations
     async function bootDevSession(configParam: ResolvedConfig) {
       const projectClient = await getProjectClient({
         accessToken: options.login.auth.accessToken,
         apiUrl: options.login.auth.apiUrl,
         projectRef: configParam.project,
         env: "dev",
+        branch,
         profile: options.profile,
       });
 
@@ -262,6 +316,7 @@ async function startDev(options: StartDevOptions) {
 
       return startDevSession({
         name: projectClient.name,
+        branch,
         rawArgs: options,
         rawConfig: configParam,
         client: projectClient.client,
@@ -274,7 +329,7 @@ async function startDev(options: StartDevOptions) {
 
     devInstance = await bootDevSession(watcher.config);
 
-    const waitUntilExit = async () => {};
+    const waitUntilExit = async () => { };
 
     return {
       watcher,
@@ -290,3 +345,87 @@ async function startDev(options: StartDevOptions) {
     throw error;
   }
 }
+
+async function devArchiveCommand(dir: string, options: unknown) {
+  return await wrapCommandAction(
+    "devArchiveCommand",
+    DevArchiveCommandOptions,
+    options,
+    async (opts) => {
+      return await archiveDevBranchCommand(dir, opts);
+    }
+  );
+}
+
+
+async function archiveDevBranchCommand(dir: string, options: DevArchiveCommandOptions) {
+  intro(`Archiving dev branch`);
+
+  if (!options.skipUpdateCheck) {
+    await updateTriggerPackages(dir, { ...options }, true, true);
+  }
+
+  const cwd = process.cwd();
+  const projectPath = resolve(cwd, dir);
+
+  verifyDirectory(dir, projectPath);
+
+  const authorization = await login({
+    embedded: true,
+    defaultApiUrl: options.apiUrl,
+    profile: options.profile,
+  });
+
+  if (!authorization.ok) {
+    if (authorization.error === "fetch failed") {
+      throw new Error(
+        `Failed to connect to ${authorization.auth?.apiUrl}. Are you sure it's the correct URL?`
+      );
+    } else {
+      throw new Error(
+        `You must login first. Use the \`login\` CLI command.\n\n${authorization.error}`
+      );
+    }
+  }
+
+  const resolvedConfig = await loadConfig({
+    cwd: projectPath,
+    overrides: { project: options.projectRef },
+    configFile: options.config,
+  });
+
+  logger.debug("Resolved config", resolvedConfig);
+
+  const branch = getDevBranch({ specified: options.branch });
+
+  if (!branch) {
+    throw new Error(
+      "Didn't auto-detect branch, so you need to specify a dev branch. Use --branch <branch>."
+    );
+  }
+
+  const $buildSpinner = spinner();
+  $buildSpinner.start(`Archiving "${branch}"`);
+  const result = await archiveDevBranch(authorization, branch, resolvedConfig.project);
+  $buildSpinner.stop(
+    result ? `Successfully archived "${branch}"` : `Failed to archive "${branch}".`
+  );
+  return result;
+}
+
+async function archiveDevBranch(
+  authorization: LoginResultOk,
+  branch: string,
+  project: string
+) {
+  const apiClient = new CliApiClient(authorization.auth.apiUrl, authorization.auth.accessToken);
+
+  const result = await apiClient.archiveBranch(project, "development", branch);
+
+  if (result.success) {
+    return true;
+  } else {
+    logger.error(result.error);
+    return false;
+  }
+}