@postman-cse/onboarding-repo-sync 2.1.6 → 2.1.8

package/dist/cli.cjs

@@ -123217,12 +123217,14 @@ var POSTMAN_ENDPOINT_PROFILES = {
   prod: {
     apiBaseUrl: "https://api.getpostman.com",
     bifrostBaseUrl: "https://bifrost-premium-https-v4.gw.postman.com",
+    fallbackBaseUrl: "https://go.postman.co/_api",
     cliInstallUrl: "https://dl-cli.pstmn.io/install/unix.sh",
     iapubBaseUrl: "https://iapub.postman.co"
   },
   beta: {
     apiBaseUrl: "https://api.getpostman-beta.com",
     bifrostBaseUrl: "https://bifrost-https-v4.gw.postman-beta.com",
+    fallbackBaseUrl: "https://go.postman-beta.co/_api",
     cliInstallUrl: "https://dl-cli.pstmn-beta.io/install/unix.sh",
     iapubBaseUrl: "https://iapub.postman.co"
   }
@@ -124996,7 +124998,85 @@ var BifrostInternalIntegrationAdapter = class {
       throw advised ?? httpErr;
     }
   }
-  async connectWorkspaceToRepository(workspaceId, repoUrl) {
+  /**
+   * Probe who (if anyone) already owns the global `(repo, path)` filesystem
+   * link. Non-fatal: unexpected statuses / network errors yield `unknown` so
+   * callers can proceed and rely on reactive POST conflict handling.
+   *
+   * Bifrost states (FileSystemController.fetchWorkspaceForFileSystem):
+   *   - 200 + data null  -> free
+   *   - 200 + data       -> linked-visible (workspace payload)
+   *   - 403 + error.meta.workspaceId -> linked-invisible
+   *   - 200 + error.meta.workspaceId -> linked-invisible (proxy envelope)
+   */
+  async findWorkspaceForRepo(repoUrl, path5 = "/") {
+    const fsPath = path5 && path5.trim() ? path5.trim() : "/";
+    const url = `${this.bifrostBaseUrl}/ws/proxy`;
+    const payload = {
+      service: "workspaces",
+      method: "GET",
+      path: `/workspaces/filesystem?repo=${encodeURIComponent(repoUrl)}&path=${encodeURIComponent(fsPath)}`
+    };
+    try {
+      const response = await this.fetchImpl(url, {
+        method: "POST",
+        headers: this.bifrostHeaders(),
+        body: JSON.stringify(payload)
+      });
+      let parsed = {};
+      try {
+        parsed = await response.json();
+      } catch {
+        return {
+          state: "unknown",
+          reason: `filesystem lookup returned non-JSON body (HTTP ${response.status})`
+        };
+      }
+      const errorMetaWorkspaceId = typeof parsed?.error?.meta?.workspaceId === "string" && parsed.error.meta.workspaceId.trim() ? parsed.error.meta.workspaceId.trim() : void 0;
+      if (errorMetaWorkspaceId) {
+        return { state: "linked-invisible", workspaceId: errorMetaWorkspaceId };
+      }
+      if (response.ok) {
+        if (parsed?.data == null) {
+          return { state: "free" };
+        }
+        const id = typeof parsed.data.id === "string" ? parsed.data.id.trim() : "";
+        if (!id) {
+          return {
+            state: "unknown",
+            reason: "filesystem lookup returned 200 without a workspace id"
+          };
+        }
+        const name = typeof parsed.data.name === "string" && parsed.data.name.trim() ? parsed.data.name.trim() : void 0;
+        return {
+          state: "linked-visible",
+          workspace: name ? { id, name } : { id }
+        };
+      }
+      if (response.status === 403) {
+        const workspaceId = extractDuplicateWorkspaceId(
+          JSON.stringify(parsed)
+        );
+        if (workspaceId) {
+          return { state: "linked-invisible", workspaceId };
+        }
+        return {
+          state: "unknown",
+          reason: "filesystem lookup returned 403 without error.meta.workspaceId"
+        };
+      }
+      return {
+        state: "unknown",
+        reason: `filesystem lookup returned HTTP ${response.status}`
+      };
+    } catch (error) {
+      return {
+        state: "unknown",
+        reason: error instanceof Error ? error.message : String(error)
+      };
+    }
+  }
+  async connectWorkspaceToRepository(workspaceId, repoUrl, options) {
     const url = `${this.bifrostBaseUrl}/ws/proxy`;
     const payload = {
       service: "workspaces",
@@ -125023,6 +125103,11 @@ var BifrostInternalIntegrationAdapter = class {
         if (isDuplicate) {
           const existingWorkspaceId = extractDuplicateWorkspaceId(body);
           if (existingWorkspaceId && existingWorkspaceId !== workspaceId) {
+            if (options?.preflightWasFree) {
+              throw new Error(
+                `REPOSITORY_LINK_CONFLICT_UNRESOLVED: Preflight found no active owner, but link creation reported workspace ${existingWorkspaceId}. Stop and contact Postman support; do not alter the repository URL.`
+              );
+            }
             throw new Error(
               await this.describeWorkspaceLinkConflict(existingWorkspaceId, workspaceId, repoUrl)
             );
@@ -125690,6 +125775,14 @@ var PostmanGatewayAssetsClient = class {
     createFlights.set(key, { fingerprint, promise: pending });
     return pending;
   }
+  /**
+   * Reconcile an ambiguous create. Returns the adopted match, `undefined`
+   * when every discovery read succeeded and found nothing (the create is
+   * conclusively absent, so a fallback resend cannot duplicate), or `null`
+   * when the outcome is inconclusive (non-ambiguous error, or a discovery
+   * read itself failed — in that case a resend could duplicate a committed
+   * twin and must not fire).
+   */
   async discoverAfterAmbiguousCreate(discover, error) {
     if (!this.isAmbiguousCreateOutcome(error)) {
       return null;
@@ -125698,12 +125791,31 @@ var PostmanGatewayAssetsClient = class {
       if (attempt > 0) {
         await this.sleep(this.reconcileDelayMs);
       }
-      const found = await discover();
+      let found;
+      try {
+        found = await discover();
+      } catch {
+        return null;
+      }
       if (found) {
         return found;
       }
     }
-    return null;
+    return void 0;
+  }
+  /**
+   * After an ambiguous create failed AND discovery proved the asset absent,
+   * re-attempt the create once with the cold `/_api` fallback enabled: the
+   * reconcile above guarantees no committed twin, so the resend cannot
+   * duplicate. Returns null when the resend also fails (caller rethrows the
+   * original error).
+   */
+  async resendAbsentCreate(operation) {
+    try {
+      return await operation();
+    } catch {
+      return null;
+    }
   }
   publicEnvironmentUid(data, bareId) {
     const owner = String(data?.owner ?? "").trim();
@@ -125751,17 +125863,18 @@ var PostmanGatewayAssetsClient = class {
         name: envName,
         values: normalizedValues
       };
+      const send2 = (fallback) => this.gateway.requestJson(
+        {
+          service: "sync",
+          method: "post",
+          path: `/environment/import?workspace=${ws}`,
+          body,
+          ...fallback ? { fallback } : {}
+        },
+        { retryTransient: false }
+      );
       try {
-        const response = await this.gateway.requestJson(
-          {
-            service: "sync",
-            method: "post",
-            path: `/environment/import?workspace=${ws}`,
-            body
-          },
-          { retryTransient: false }
-        );
-        const data = this.dataOf(response);
+        const data = this.dataOf(await send2());
         const bareId = this.idOf(data);
         if (!bareId) {
           throw new Error("Environment import did not return a UID");
@@ -125776,6 +125889,15 @@ var PostmanGatewayAssetsClient = class {
           await this.updateEnvironment(adopted, envName, values);
           return adopted;
         }
+        if (adopted === void 0) {
+          const retried = await this.resendAbsentCreate(async () => {
+            const data = this.dataOf(await send2("auto"));
+            const bareId = this.idOf(data);
+            if (!bareId) throw new Error("Environment import did not return a UID");
+            return this.publicEnvironmentUid(data, bareId);
+          });
+          if (retried) return retried;
+        }
         throw error;
       }
     });
@@ -125907,19 +126029,20 @@ var PostmanGatewayAssetsClient = class {
         private: false,
         ...environment ? { environment } : {}
       };
-      try {
-        const response = await this.gateway.requestJson(
-          {
-            service: "mock",
-            method: "post",
-            path: `/mocks?workspace=${ws}`,
-            body
-          },
-          // Unsafe create: never blind re-POST. An ESOCKETTIMEDOUT after accept
-          // may still have created the mock; reconcile via discovery below and
-          // let the orchestrator retry the whole create-or-adopt cycle.
-          { retryTransient: false }
-        );
+      const send2 = (fallback) => this.gateway.requestJson(
+        {
+          service: "mock",
+          method: "post",
+          path: `/mocks?workspace=${ws}`,
+          body,
+          ...fallback ? { fallback } : {}
+        },
+        // Unsafe create: never blind re-POST. An ESOCKETTIMEDOUT after accept
+        // may still have created the mock; reconcile via discovery below and
+        // let the orchestrator retry the whole create-or-adopt cycle.
+        { retryTransient: false }
+      );
+      const parseMock = (response) => {
         const record = this.dataOf(response);
         const uid = this.idOf(record);
         if (!uid) {
@@ -125929,6 +126052,9 @@ var PostmanGatewayAssetsClient = class {
           uid,
           url: String(record?.url ?? record?.mockUrl ?? "").trim()
         };
+      };
+      try {
+        return parseMock(await send2());
       } catch (error) {
         const adopted = await this.discoverAfterAmbiguousCreate(
           () => this.findMockByCollection(collection, environment, mockName),
@@ -125937,6 +126063,10 @@ var PostmanGatewayAssetsClient = class {
         if (adopted) {
           return { uid: adopted.uid, url: adopted.mockUrl };
         }
+        if (adopted === void 0) {
+          const retried = await this.resendAbsentCreate(async () => parseMock(await send2("auto")));
+          if (retried) return retried;
+        }
         throw error;
       }
     });
@@ -126043,21 +126173,25 @@ var PostmanGatewayAssetsClient = class {
         distribution: null,
         ...environment ? { environment } : {}
       };
-      try {
-        const response = await this.gateway.requestJson(
-          {
-            service: "monitors",
-            method: "post",
-            path: `/jobTemplates?workspace=${ws}`,
-            body
-          },
-          { retryTransient: false }
-        );
+      const send2 = (fallback) => this.gateway.requestJson(
+        {
+          service: "monitors",
+          method: "post",
+          path: `/jobTemplates?workspace=${ws}`,
+          body,
+          ...fallback ? { fallback } : {}
+        },
+        { retryTransient: false }
+      );
+      const parseMonitor = (response) => {
         const uid = this.idOf(this.dataOf(response));
         if (!uid) {
           throw new Error("Monitor create did not return a UID");
         }
         return uid;
+      };
+      try {
+        return parseMonitor(await send2());
       } catch (error) {
         const adopted = await this.discoverAfterAmbiguousCreate(
           () => this.findMonitorByCollection(collection, environment, monitorName),
@@ -126066,6 +126200,10 @@ var PostmanGatewayAssetsClient = class {
         if (adopted?.uid) {
           return adopted.uid;
         }
+        if (adopted === void 0) {
+          const retried = await this.resendAbsentCreate(async () => parseMonitor(await send2("auto")));
+          if (retried) return retried;
+        }
         throw error;
       }
     });
@@ -126294,6 +126432,7 @@ var AccessTokenGatewayClient = class {
   fetchImpl;
   secretMasker;
   maxRetries;
+  fallbackBaseUrl;
   retryBaseDelayMs;
   sleepImpl;
   constructor(options) {
@@ -126306,6 +126445,8 @@ var AccessTokenGatewayClient = class {
     this.fetchImpl = options.fetchImpl ?? fetch;
     this.secretMasker = options.secretMasker ?? createSecretMasker([this.tokenProvider.current()]);
     this.maxRetries = options.maxRetries ?? 3;
+    const fallbackEnv = typeof process !== "undefined" ? process.env?.POSTMAN_ITEM_CREATE_FALLBACK : void 0;
+    this.fallbackBaseUrl = fallbackEnv === "off" ? void 0 : options.fallbackBaseUrl?.replace(/\/+$/, "");
     this.retryBaseDelayMs = options.retryBaseDelayMs ?? 400;
     this.sleepImpl = options.sleepImpl ?? defaultSleep;
   }
@@ -126324,8 +126465,8 @@ var AccessTokenGatewayClient = class {
     }
     return headers;
   }
-  async send(request) {
-    const url = `${this.bifrostBaseUrl}/ws/proxy`;
+  async send(request, baseUrl) {
+    const url = `${baseUrl ?? this.bifrostBaseUrl}/ws/proxy`;
     return this.fetchImpl(url, {
       method: "POST",
       headers: this.buildHeaders(request.headers),
@@ -126338,6 +126479,43 @@ var AccessTokenGatewayClient = class {
       })
     });
   }
+  /**
+   * One cold, serial attempt against the fallback base URL after the primary
+   * budget is exhausted on a transient failure. Never hedged in parallel with
+   * the primary; only fires when the request would otherwise throw. Callers
+   * with `retryTransient: false` still reconcile first — the fallback attempt
+   * here is the resend, so it is only used for requests whose mutation is
+   * known idempotent or already reconciled by the caller's adopt-on-ambiguous
+   * loop.
+   */
+  async tryFallback(request) {
+    if (!this.fallbackBaseUrl) return null;
+    try {
+      return await this.send(request, this.fallbackBaseUrl);
+    } catch {
+      return null;
+    }
+  }
+  /**
+   * Run the fallback attempt and classify its response the same way the
+   * primary path would. Returns the success response, or null when the
+   * fallback also failed transiently (caller then throws the original error).
+   * Non-transient fallback failures (4xx) surface as their own HttpError since
+   * they are the freshest authoritative answer.
+   */
+  fallbackEligible(request, retryTransient) {
+    if (!this.fallbackBaseUrl) return false;
+    return retryTransient || request.fallback === "auto";
+  }
+  async attemptFallback(request, retryTransient) {
+    if (!this.fallbackEligible(request, retryTransient)) return null;
+    const response = await this.tryFallback(request);
+    if (!response) return null;
+    if (response.ok) return response;
+    const body = await response.text().catch(() => "");
+    if (isRetryableSafeReadResponse(response.status)) return null;
+    throw this.toHttpError(request, response, body);
+  }
   /**
    * Send a gateway request, refreshing the token once on an auth failure and
    * optionally retrying transient downstream failures (5xx / Bifrost read
@@ -126360,6 +126538,8 @@ var AccessTokenGatewayClient = class {
           await this.sleepImpl(delay);
           continue;
         }
+        const fallbackResponse2 = await this.attemptFallback(request, retryTransient);
+        if (fallbackResponse2) return fallbackResponse2;
         throw error;
       }
       if (response.ok) {
@@ -126381,6 +126561,8 @@ var AccessTokenGatewayClient = class {
         await this.sleepImpl(delay);
         continue;
       }
+      const fallbackResponse = await this.attemptFallback(request, retryTransient);
+      if (fallbackResponse) return fallbackResponse;
       throw this.toHttpError(request, response, body);
     }
   }
@@ -126952,6 +127134,7 @@ function resolveInputs(env = process.env) {
     postmanStack,
     postmanApiBase: endpointProfile.apiBaseUrl,
     postmanBifrostBase: endpointProfile.bifrostBaseUrl,
+    postmanFallbackBase: endpointProfile.fallbackBaseUrl,
     postmanCliInstallUrl: endpointProfile.cliInstallUrl,
     postmanIapubBase: endpointProfile.iapubBaseUrl
   };
@@ -127658,6 +127841,39 @@ async function runRepoSyncInner(inputs, dependencies) {
       }
     }
   }
+  let skipRepositoryLinkPost = false;
+  let repositoryLinkPreflightWasFree = false;
+  if (inputs.workspaceLinkEnabled && inputs.workspaceId && inputs.repoUrl && dependencies.internalIntegration?.findWorkspaceForRepo) {
+    const probe = await dependencies.internalIntegration.findWorkspaceForRepo(
+      inputs.repoUrl,
+      "/"
+    );
+    if (probe.state === "linked-visible") {
+      if (probe.workspace.id === inputs.workspaceId) {
+        skipRepositoryLinkPost = true;
+        dependencies.core.info(
+          `REPOSITORY_LINK_ALREADY_TARGET: Repository ${inputs.repoUrl} at path / is already linked to target workspace ${inputs.workspaceId}; continuing.`
+        );
+      } else {
+        const ownerName = probe.workspace.name?.trim() || "unknown";
+        throw new Error(
+          `REPOSITORY_LINK_CONFLICT_VISIBLE: Repository ${inputs.repoUrl} at path / is already linked to workspace ${probe.workspace.id} ("${ownerName}"). No Postman assets were changed. Reuse that workspace or disconnect it in Workspace Settings, then rerun.`
+        );
+      }
+    } else if (probe.state === "linked-invisible") {
+      let message = `REPOSITORY_LINK_CONFLICT_INVISIBLE: Repository ${inputs.repoUrl} at path / is linked to workspace ${probe.workspaceId}, but these credentials cannot view it. No Postman assets were changed. Ask its owner or a team admin to disconnect it.`;
+      if (inputs.orgMode) {
+        message += " Verify workspace-team-id; if the owner is in another sub-team, ask that sub-team's admin to disconnect it.";
+      }
+      throw new Error(message);
+    } else if (probe.state === "free") {
+      repositoryLinkPreflightWasFree = true;
+    } else {
+      dependencies.core.warning(
+        `REPOSITORY_LINK_PREFLIGHT_UNKNOWN: Unable to determine the existing repository link (${probe.reason}); continuing and relying on link creation conflict handling.`
+      );
+    }
+  }
   const branchAssetMarker = buildBranchAssetMarker(branchDecision, inputs);
   const envUids = await upsertEnvironments(inputs, dependencies, resourcesState, branchAssetMarker);
   outputs["environment-uids-json"] = JSON.stringify(envUids);
@@ -127790,18 +128006,33 @@ async function runRepoSyncInner(inputs, dependencies) {
   }
   if (inputs.workspaceLinkEnabled && inputs.workspaceId && inputs.repoUrl && dependencies.internalIntegration) {
     try {
-      await dependencies.internalIntegration.connectWorkspaceToRepository(
-        inputs.workspaceId,
-        inputs.repoUrl
-      );
-      outputs["workspace-link-status"] = "success";
-      dependencies.core.info(
-        `workspace-link-status=success workspace-id=${inputs.workspaceId} repo=${inputs.repoUrl}`
-      );
+      if (skipRepositoryLinkPost) {
+        outputs["workspace-link-status"] = "success";
+        dependencies.core.info(
+          `workspace-link-status=success workspace-id=${inputs.workspaceId} repo=${inputs.repoUrl} (preflight already-target; link POST skipped)`
+        );
+      } else {
+        await dependencies.internalIntegration.connectWorkspaceToRepository(
+          inputs.workspaceId,
+          inputs.repoUrl,
+          repositoryLinkPreflightWasFree ? { preflightWasFree: true } : void 0
+        );
+        outputs["workspace-link-status"] = "success";
+        dependencies.core.info(
+          `workspace-link-status=success workspace-id=${inputs.workspaceId} repo=${inputs.repoUrl}`
+        );
+      }
     } catch (error) {
       outputs["workspace-link-status"] = "failed";
-      const message = `Workspace link failed: ${error instanceof Error ? error.message : String(error)}`;
+      const rawMessage = error instanceof Error ? error.message : String(error);
+      const isUnresolvedContract = rawMessage.startsWith(
+        "REPOSITORY_LINK_CONFLICT_UNRESOLVED:"
+      );
+      const message = isUnresolvedContract ? rawMessage : `Workspace link failed: ${rawMessage}`;
       if (branchDecision.tier === "canonical") {
+        if (isUnresolvedContract && error instanceof Error) {
+          throw error;
+        }
         throw new Error(message, { cause: error });
       }
       dependencies.core.warning(message);
@@ -127955,6 +128186,8 @@ async function resolvePostmanApiKeyAndTeamId(inputs, actionCore, actionExec, mas
       const gateway = new AccessTokenGatewayClient({
         tokenProvider,
         bifrostBaseUrl: inputs.postmanBifrostBase,
+        // No fallback on the org-mode probe: the expected non-org 400 must
+        // surface verbatim, not be re-fired against the /_api alias.
         secretMasker: masker
       });
       const squads = await gateway.getSquads(teamId);
@@ -128010,6 +128243,7 @@ function createRepoSyncDependencies(inputs, resolved, factories, options = {}) {
   const gateway = new AccessTokenGatewayClient({
     tokenProvider,
     bifrostBaseUrl: inputs.postmanBifrostBase,
+    fallbackBaseUrl: inputs.postmanFallbackBase,
     teamId: resolved.teamId,
     orgMode: inputs.orgMode,
     secretMasker: masker