@salesforce/plugin-devops-center 1.2.28 → 1.3.0

package/lib/utils/addStageEnvironment.d.ts

@@ -0,0 +1,92 @@
+import { Connection } from '@salesforce/core';
+export type OrgType = 'Production' | 'Sandbox';
+export declare const POLL_INTERVAL_MS = 3000;
+export declare const POLL_TIMEOUT_MS: number;
+export type AddStageEnvironmentParams = {
+    connection: Connection;
+    pipelineId: string;
+    stageId: string;
+    environmentName: string;
+    orgType: OrgType;
+};
+export type AddStageEnvironmentResult = {
+    success: boolean;
+    stageId: string;
+    environmentId?: string;
+    environmentName?: string;
+    orgType?: OrgType;
+    pipelineId?: string;
+    redirectUrl?: string;
+    namedCredential?: string;
+    organizationId?: string;
+    error?: string;
+};
+type EnvironmentCreateResponse = {
+    id: string;
+    name: string;
+    redirectUrl: string;
+    namedCredential: string;
+    externalCredential: string;
+    pipelineId?: string;
+};
+export type EnvironmentGetResponse = {
+    id: string;
+    name: string;
+    organizationId?: string;
+    orgType?: string;
+    namedCredential?: string;
+    redirectUrl?: string;
+};
+type EnvironmentValidateResponse = {
+    id: string;
+    name: string;
+    organizationId?: string;
+    orgType?: string;
+    namedCredential?: string;
+};
+/**
+ * Creates an environment and associates it with a pipeline stage via the Connect API.
+ * POST /services/data/v{version}/connect/devops/environment
+ */
+export declare function createEnvironment(connection: Connection, params: {
+    pipelineId: string;
+    stageId: string;
+    environmentName: string;
+    orgType: OrgType;
+}): Promise<EnvironmentCreateResponse>;
+/**
+ * Fetches the current state of an environment.
+ * GET /services/data/v{version}/connect/devops/environment/{environmentId}
+ */
+export declare function getEnvironment(connection: Connection, environmentId: string): Promise<EnvironmentGetResponse>;
+/**
+ * Validates an authenticated environment by triggering server-side org extraction.
+ * PATCH /services/data/v{version}/connect/devops/environment/{environmentId}
+ */
+export declare function validateEnvironment(connection: Connection, environmentId: string): Promise<EnvironmentValidateResponse>;
+/**
+ * Polls until authentication is complete by attempting PATCH validation.
+ * The PATCH call triggers server-side org extraction; if the user has
+ * completed OAuth, it returns a response with organizationId populated.
+ * If auth isn't done yet, the PATCH throws — we catch and retry.
+ * Falls back to GET polling as a secondary check.
+ * Throws on timeout.
+ */
+export declare function pollForAuthentication(connection: Connection, environmentId: string, timeoutMs?: number, intervalMs?: number): Promise<EnvironmentValidateResponse>;
+/**
+ * Full orchestration: create environment -> poll for auth -> validate.
+ * Returns the final result including organizationId.
+ *
+ * The caller is responsible for opening the browser at the returned redirectUrl
+ * and displaying progress to the user. Use `onCreated` to receive the redirect URL
+ * before polling begins.
+ */
+export declare function addStageEnvironment(params: AddStageEnvironmentParams & {
+    onCreated?: (data: {
+        environmentId: string;
+        redirectUrl: string;
+    }) => void;
+    pollTimeoutMs?: number;
+    pollIntervalMs?: number;
+}): Promise<AddStageEnvironmentResult>;
+export {};

package/lib/utils/addStageEnvironment.js

@@ -0,0 +1,120 @@
+/*
+ * Copyright 2026, Salesforce, Inc.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+const ORG_TYPE_API_MAP = {
+    Production: 'PRODUCTION',
+    Sandbox: 'SANDBOX',
+};
+export const POLL_INTERVAL_MS = 3000;
+export const POLL_TIMEOUT_MS = 5 * 60 * 1000;
+/**
+ * Creates an environment and associates it with a pipeline stage via the Connect API.
+ * POST /services/data/v{version}/connect/devops/environment
+ */
+export async function createEnvironment(connection, params) {
+    const path = `/services/data/v${connection.getApiVersion()}/connect/devops/environment`;
+    return connection.request({
+        method: 'POST',
+        url: path,
+        body: JSON.stringify({
+            envName: params.environmentName,
+            orgType: ORG_TYPE_API_MAP[params.orgType],
+            pipelineStageId: params.stageId,
+            pipelineId: params.pipelineId,
+        }),
+        headers: { 'Content-Type': 'application/json' },
+    });
+}
+/**
+ * Fetches the current state of an environment.
+ * GET /services/data/v{version}/connect/devops/environment/{environmentId}
+ */
+export async function getEnvironment(connection, environmentId) {
+    const path = `/services/data/v${connection.getApiVersion()}/connect/devops/environment/${environmentId}`;
+    return connection.request({ method: 'GET', url: path });
+}
+/**
+ * Validates an authenticated environment by triggering server-side org extraction.
+ * PATCH /services/data/v{version}/connect/devops/environment/{environmentId}
+ */
+export async function validateEnvironment(connection, environmentId) {
+    const path = `/services/data/v${connection.getApiVersion()}/connect/devops/environment/${environmentId}`;
+    return connection.request({
+        method: 'PATCH',
+        url: path,
+        body: JSON.stringify({}),
+        headers: { 'Content-Type': 'application/json' },
+    });
+}
+function sleep(ms) {
+    return new Promise((resolve) => {
+        setTimeout(resolve, ms);
+    });
+}
+/**
+ * Polls until authentication is complete by attempting PATCH validation.
+ * The PATCH call triggers server-side org extraction; if the user has
+ * completed OAuth, it returns a response with organizationId populated.
+ * If auth isn't done yet, the PATCH throws — we catch and retry.
+ * Falls back to GET polling as a secondary check.
+ * Throws on timeout.
+ */
+// eslint-disable-next-line no-await-in-loop -- polling requires sequential awaits by design
+export async function pollForAuthentication(connection, environmentId, timeoutMs = POLL_TIMEOUT_MS, intervalMs = POLL_INTERVAL_MS) {
+    const deadline = Date.now() + timeoutMs;
+    while (Date.now() < deadline) {
+        try {
+            // eslint-disable-next-line no-await-in-loop
+            const validated = await validateEnvironment(connection, environmentId);
+            if (validated.organizationId) {
+                return validated;
+            }
+        }
+        catch {
+            // PATCH failed — auth likely not yet complete, continue polling
+        }
+        // eslint-disable-next-line no-await-in-loop
+        await sleep(intervalMs);
+    }
+    throw new Error(`Authentication timed out after ${timeoutMs / 1000} seconds. Re-run the command or authenticate manually.`);
+}
+/**
+ * Full orchestration: create environment -> poll for auth -> validate.
+ * Returns the final result including organizationId.
+ *
+ * The caller is responsible for opening the browser at the returned redirectUrl
+ * and displaying progress to the user. Use `onCreated` to receive the redirect URL
+ * before polling begins.
+ */
+export async function addStageEnvironment(params) {
+    const { connection, pipelineId, stageId, environmentName, orgType, onCreated, pollTimeoutMs, pollIntervalMs } = params;
+    const createData = await createEnvironment(connection, { pipelineId, stageId, environmentName, orgType });
+    if (onCreated) {
+        onCreated({ environmentId: createData.id, redirectUrl: createData.redirectUrl });
+    }
+    const validated = await pollForAuthentication(connection, createData.id, pollTimeoutMs, pollIntervalMs);
+    return {
+        success: true,
+        stageId,
+        environmentId: createData.id,
+        environmentName: createData.name,
+        orgType,
+        pipelineId,
+        redirectUrl: createData.redirectUrl,
+        namedCredential: createData.namedCredential ?? validated.namedCredential,
+        organizationId: validated.organizationId,
+    };
+}
+//# sourceMappingURL=addStageEnvironment.js.map

package/lib/utils/addStageEnvironment.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"addStageEnvironment.js","sourceRoot":"","sources":["../../src/utils/addStageEnvironment.ts"],"names":[],"mappings":"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"}

package/messages/devops.stage.add-branch.md

@@ -0,0 +1,46 @@
+# summary
+
+Add a source code repository branch to a pipeline stage.
+
+# description
+
+By default, the branch must exist in the repository. Use --create-vcs-branch to create a branch if it doesn't exist.
+Each pipeline stage supports only one branch. Adding a branch replaces any existing branch linked to the pipeline stage.
+
+# flags.pipeline-id.summary
+
+ID of the pipeline that contains the stage.
+
+# flags.stage-id.summary
+
+ID of the pipeline stage to associate the branch with.
+
+# flags.branch-name.summary
+
+Name of the repository branch to assign to the stage.
+
+# flags.create-vcs-branch.summary
+
+Create the branch in the remote repository if it doesn't already exist.
+
+# examples
+
+- Add an existing branch to a stage:
+
+      <%= config.bin %> <%= command.id %> --target-org my-devops-org --pipeline-id 0Xo000000000001 --stage-id 0Xp000000000001 --branch-name main
+
+- Create and add a branch to a pipeline stage:
+
+      <%= config.bin %> <%= command.id %> --target-org my-devops-org --pipeline-id 0Xo000000000001 --stage-id 0Xp000000000002 --branch-name integration --create-vcs-branch
+
+# error.StageNotFound
+
+Pipeline stage "%s" doesn't exist in pipeline "%s". Check the stage ID and try again.
+
+# error.NextStageNoBranch
+
+You must set up a branch on stage "%s" before configuring stage "%s". Branches must be configured from right to left (starting from the last stage in the pipeline).
+
+# error.BranchAttachFailed
+
+Failed to associate branch with stage: %s

package/messages/devops.stage.add-environment.md

@@ -0,0 +1,61 @@
+# summary
+
+Add a Salesforce environment to a pipeline stage.
+
+# description
+
+This command triggers an OAuth flow to authenticate the environment. A browser window opens automatically for you to log in.
+
+# flags.pipeline-id.summary
+
+ID of the pipeline that contains the stage.
+
+# flags.stage-id.summary
+
+ID of the pipeline stage.
+
+# flags.environment-name.summary
+
+Name of the environment.
+
+# flags.org-type.summary
+
+Type of the Salesforce org. Valid values: Production, Sandbox.
+
+# flags.no-browser.summary
+
+Don't auto-open the browser for OAuth authentication. The redirect URL is printed for manual use.
+
+# examples
+
+- Add a production environment to a stage using its ID:
+
+      <%= config.bin %> <%= command.id %> --target-org my-devops-org --stage-id 0Xp000000000001 --environment-name Production_Org --org-type Production
+
+# info.BrowserOpened
+
+A browser window has been opened for authentication. Log in to the target org to complete the setup.
+
+# info.ManualAuth
+
+Open the following URL in your browser to authenticate the environment:\n%s
+
+# info.WaitingForAuth
+
+Waiting for authentication to complete...
+
+# info.Success
+
+Successfully added environment to the stage.
+
+# error.StageNotFound
+
+Pipeline stage "%s" doesn't exist in pipeline "%s". Check the stage ID and try again.
+
+# error.EnvironmentAttachFailed
+
+Failed to create environment for stage: %s
+
+# error.AuthTimeout
+
+Authentication timed out. The environment was created but not yet authenticated. Re-run the command or authenticate manually via the org's DevOps Center setup.

package/npm-shrinkwrap.json

@@ -1,12 +1,12 @@
 {
   "name": "@salesforce/plugin-devops-center",
-  "version": "1.2.28",
+  "version": "1.3.0",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@salesforce/plugin-devops-center",
-      "version": "1.2.28",
+      "version": "1.3.0",
       "license": "Apache-2.0",
       "dependencies": {
         "@jsforce/jsforce-node": "^3",