@postman-cse/onboarding-repo-sync 2.1.19 → 2.3.0

package/dist/cli.cjs

@@ -134765,6 +134765,17 @@ var postmanRepoSyncActionContract = {
       description: "Existing mock server URL. When set, the action validates and reuses this mock instead of creating a new one.",
       required: false
     },
+    "mock-visibility": {
+      description: "Required mock access policy. Public is anonymous; private requires a runtime x-api-key supplied by the caller and is never persisted by repo-sync.",
+      required: false,
+      default: "public",
+      allowedValues: ["public", "private"]
+    },
+    "mock-environment-enabled": {
+      description: "Create or update a dedicated manual-validation environment whose baseUrl is the validated mock URL. This environment is excluded from runtime CI selection and never contains a mock credential.",
+      required: false,
+      default: "false"
+    },
     "monitor-cron": {
       description: "Cron expression for monitor scheduling (e.g. '0 */6 * * *'). When empty, the monitor is created disabled and triggered to run once per workflow invocation (and once on every subsequent run).",
       required: false,
@@ -134958,6 +134969,18 @@ var postmanRepoSyncActionContract = {
     "mock-url": {
       description: "Created or reused mock server URL."
     },
+    "mock-visibility": {
+      description: "Authoritatively observed mock visibility: public or private."
+    },
+    "mock-auth-required": {
+      description: "Whether the collection runner must supply postmanPrivateMockApiKey at runtime."
+    },
+    "mock-environment-uid": {
+      description: "Dedicated manual-validation environment UID when mock-environment-enabled succeeds."
+    },
+    "mock-environment-status": {
+      description: "Whether the optional manual-validation mock environment succeeded, was skipped, or failed."
+    },
     "monitor-id": {
       description: "Created or reused smoke monitor ID."
     },
@@ -135052,19 +135075,30 @@ var MockContractError = class extends Error {
     this.name = "MockContractError";
   }
 };
-function requirePublicMock(mock) {
-  if (mock.visibility === "private") {
+function requireMockVisibility(mock, requested) {
+  if (mock.visibility === "unknown") {
     throw new MockContractError(
-      `MOCK_NOT_PUBLIC: Mock ${mock.uid} is private. Make it public in Postman or remove/rename it so repo-sync can create the canonical public mock.`
+      `MOCK_VISIBILITY_UNKNOWN: Mock ${mock.uid} did not expose a supported visibility field. Refusing to assume it is callable.`
     );
   }
-  if (mock.visibility !== "public") {
+  if (mock.visibility !== requested) {
+    const code = requested === "public" ? "MOCK_NOT_PUBLIC" : "MOCK_NOT_PRIVATE";
     throw new MockContractError(
-      `MOCK_VISIBILITY_UNKNOWN: Mock ${mock.uid} did not expose a supported visibility field. Refusing to assume it is publicly callable.`
+      `${code}: Mock ${mock.uid} is ${mock.visibility}, but mock-visibility requires ${requested}. Change the mock visibility in Postman or set mock-visibility to ${mock.visibility}.`
     );
   }
   return mock;
 }
+var PRIVATE_MOCK_AUTH_MARKER = "postman-enterprise-automation: private-mock-auth";
+var PRIVATE_MOCK_AUTH_VARIABLE = "postmanPrivateMockApiKey";
+var PRIVATE_MOCK_AUTH_SCRIPT = [
+  `// ${PRIVATE_MOCK_AUTH_MARKER}`,
+  `var privateMockApiKey = pm.variables.get('${PRIVATE_MOCK_AUTH_VARIABLE}');`,
+  "var privateMockHost = String(pm.request.url && pm.request.url.getHost ? pm.request.url.getHost() : '');",
+  "if (privateMockApiKey && /(^|\\.)mock\\.pstmn\\.io$/i.test(privateMockHost)) {",
+  "  pm.request.headers.upsert({ key: 'x-api-key', value: privateMockApiKey });",
+  "}"
+].join("\n");
 var MAX_CREATE_FLIGHTS = 256;
 var createFlights = /* @__PURE__ */ new Map();
 var PostmanGatewayAssetsClient = class {
@@ -135572,22 +135606,22 @@ var PostmanGatewayAssetsClient = class {
     return data?.collection ?? null;
   }
   // --- mocks (service: mock) ---
-  async createMock(workspaceId, name, collectionUid, environmentUid) {
+  async createMock(workspaceId, name, collectionUid, environmentUid, requestedVisibility = "public") {
     const ws = workspaceId || this.workspaceId;
     const mockName = String(name ?? "").trim();
     const collection = String(collectionUid ?? "").trim();
     const environment = String(environmentUid ?? "").trim();
-    const flightKey = `mock:${ws}:${collection}:${environment}:${mockName}`;
+    const flightKey = `mock:${ws}:${collection}:${environment}:${requestedVisibility}:${mockName}`;
     return this.singleFlight(flightKey, flightKey, "mock", async () => {
       const existing = await this.findMockByCollection(collection, environment, mockName);
       if (existing) {
-        const reusable = requirePublicMock(existing);
-        return { uid: reusable.uid, url: reusable.mockUrl };
+        const reusable = requireMockVisibility(existing, requestedVisibility);
+        return { uid: reusable.uid, url: reusable.mockUrl, visibility: requestedVisibility };
       }
       const body = {
         name: mockName,
         collection,
-        private: false,
+        private: requestedVisibility === "private",
         ...environment ? { environment } : {}
       };
       const send2 = (fallback) => this.gateway.requestJson(
@@ -135605,12 +135639,14 @@ var PostmanGatewayAssetsClient = class {
       );
       const parseMock = (response) => {
         const record = this.dataOf(response);
-        const created = requirePublicMock(
-          this.decodeMockRecord(record, "Mock create")
+        const created = requireMockVisibility(
+          this.decodeMockRecord(record, "Mock create"),
+          requestedVisibility
         );
         return {
           uid: created.uid,
-          url: created.mockUrl
+          url: created.mockUrl,
+          visibility: requestedVisibility
         };
       };
       try {
@@ -135621,8 +135657,8 @@ var PostmanGatewayAssetsClient = class {
           error
         );
         if (adopted) {
-          const reusable = requirePublicMock(adopted);
-          return { uid: reusable.uid, url: reusable.mockUrl };
+          const reusable = requireMockVisibility(adopted, requestedVisibility);
+          return { uid: reusable.uid, url: reusable.mockUrl, visibility: requestedVisibility };
         }
         if (adopted === void 0) {
           const retried = await this.resendAbsentCreate(async () => parseMock(await send2("auto")));
@@ -135632,6 +135668,51 @@ var PostmanGatewayAssetsClient = class {
       }
     });
   }
+  /**
+   * Add a secret-free runtime hook to every HTTP request in a collection. The
+   * PMAK value is supplied only by the runner as a transient variable; this
+   * method persists the variable name and header wiring, never the credential.
+   */
+  async configurePrivateMockRuntimeAuth(collectionUid) {
+    const cid = String(collectionUid ?? "").trim();
+    if (!cid) return 0;
+    const listed = await this.gateway.requestJson({
+      service: "collection",
+      method: "get",
+      path: `/v3/collections/${cid}/items/`
+    });
+    const items = Array.isArray(listed?.data) ? listed.data : [];
+    let patched = 0;
+    for (const listedItem of items) {
+      if (String(listedItem.$kind ?? "") !== "http-request") continue;
+      const itemId = String(listedItem.id ?? "").trim();
+      if (!itemId) continue;
+      const response = await this.gateway.requestJson({
+        service: "collection",
+        method: "get",
+        path: `/v3/collections/${cid}/items/${itemId}`,
+        headers: { "X-Entity-Type": "http-request" }
+      });
+      const item = this.asRecord(response?.data) ?? listedItem;
+      const scripts = Array.isArray(item.scripts) ? item.scripts.filter((entry) => Boolean(this.asRecord(entry))) : [];
+      const before = scripts.find((script) => String(script.type ?? "") === "beforeRequest");
+      if (String(before?.code ?? "").includes(PRIVATE_MOCK_AUTH_MARKER)) continue;
+      const code = [String(before?.code ?? "").trim(), PRIVATE_MOCK_AUTH_SCRIPT].filter(Boolean).join("\n");
+      const nextScripts = [
+        ...scripts.filter((script) => String(script.type ?? "") !== "beforeRequest"),
+        { type: "beforeRequest", code, language: "text/javascript" }
+      ];
+      await this.gateway.requestJson({
+        service: "collection",
+        method: "patch",
+        path: `/v3/collections/${cid}/items/${itemId}`,
+        headers: { "X-Entity-Type": "http-request" },
+        body: [{ op: "add", path: "/scripts", value: nextScripts }]
+      });
+      patched += 1;
+    }
+    return patched;
+  }
   async listMocks() {
     const response = await this.gateway.requestJson({
       service: "mock",
@@ -136594,7 +136675,7 @@ function normalizeMockUrl(value, source) {
   url.pathname = url.pathname.replace(/\/+$/g, "") || "/";
   return url.toString();
 }
-function resolveExplicitPublicMock(mocks, explicitUrl, collectionUid, environmentUid) {
+function resolveExplicitMock(mocks, explicitUrl, collectionUid, environmentUid, requestedVisibility) {
   const normalized = normalizeMockUrl(explicitUrl, "mock-url");
   const matches = mocks.filter(
     (mock) => normalizeMockUrl(mock.mockUrl, `mock ${mock.uid} URL`) === normalized
@@ -136620,7 +136701,7 @@ function resolveExplicitPublicMock(mocks, explicitUrl, collectionUid, environmen
       `EXPLICIT_MOCK_IDENTITY_MISMATCH: Mock ${match.uid} references environment ${match.environment || "(none)"}, expected ${environmentUid}`
     );
   }
-  return requirePublicMock(match);
+  return requireMockVisibility(match, requestedVisibility);
 }
 function shouldRetryMockCreate(error) {
   if (error instanceof MockContractError) return false;
@@ -136729,6 +136810,15 @@ function parseCredentialPreflight(value) {
     `Unsupported credential-preflight "${normalized}". Supported values: ${allowed.join(", ")}`
   );
 }
+function parseMockVisibility(value) {
+  const definition = postmanRepoSyncActionContract.inputs["mock-visibility"];
+  const allowed = definition.allowedValues ?? [];
+  const normalized = String(value || "").trim() || (definition.default ?? "public");
+  if (allowed.includes(normalized)) return normalized;
+  throw new Error(
+    `Unsupported mock-visibility "${normalized}". Supported values: ${allowed.join(", ")}`
+  );
+}
 function parseBranchStrategy(value) {
   const definition = postmanRepoSyncActionContract.inputs["branch-strategy"];
   const allowed = definition.allowedValues ?? [];
@@ -136835,6 +136925,8 @@ function resolveInputs(env = process.env) {
     orgMode: parseBooleanInput(getInput("org-mode", env), false),
     monitorId: getInput("monitor-id", env),
     mockUrl: getInput("mock-url", env),
+    mockVisibility: parseMockVisibility(getInput("mock-visibility", env)),
+    mockEnvironmentEnabled: parseBooleanInput(getInput("mock-environment-enabled", env), false),
     monitorCron: getInput("monitor-cron", env),
     sslClientCert: getInput("ssl-client-cert", env),
     sslClientKey: getInput("ssl-client-key", env),
@@ -137061,6 +137153,10 @@ function createOutputs(inputs) {
     "environment-sync-status": "skipped",
     "environment-uids-json": JSON.stringify(inputs.environmentUids),
     "mock-url": "",
+    "mock-visibility": "",
+    "mock-auth-required": "false",
+    "mock-environment-uid": "",
+    "mock-environment-status": "skipped",
     "monitor-id": "",
     "repo-sync-summary-json": "{}",
     "commit-sha": "",
@@ -137189,6 +137285,52 @@ async function upsertEnvironments(inputs, dependencies, resourcesState, assetMar
   }
   return envUids;
 }
+async function upsertMockEnvironment(inputs, dependencies, assetProjectName, mockUrl) {
+  if (!inputs.mockEnvironmentEnabled || !inputs.workspaceId || !mockUrl) {
+    return "";
+  }
+  const displayName = `${assetProjectName} - Mock`;
+  const values = buildEnvironmentValues("mock", mockUrl);
+  const mask = resolveRepoSyncMasker(dependencies);
+  try {
+    const discovered = await dependencies.postman.findEnvironmentByName(
+      inputs.workspaceId,
+      displayName
+    );
+    if (discovered?.uid) {
+      try {
+        const existing = await dependencies.postman.getEnvironment(discovered.uid);
+        const currentValues = existing.data?.values ?? existing.values ?? [];
+        if (currentValues.some((value) => value.key === "baseUrl" && value.value === mockUrl)) {
+          dependencies.core.info(`Mock environment already points to ${mockUrl}: ${discovered.uid}`);
+          return discovered.uid;
+        }
+      } catch {
+      }
+      await dependencies.postman.updateEnvironment(discovered.uid, displayName, values);
+      dependencies.core.info(`Updated mock environment ${displayName}: ${discovered.uid}`);
+      return discovered.uid;
+    }
+    const uid = await dependencies.postman.createEnvironment(
+      inputs.workspaceId,
+      displayName,
+      values
+    );
+    dependencies.core.info(`Created mock environment ${displayName}: ${uid}`);
+    return uid;
+  } catch (error) {
+    dependencies.core.warning(
+      formatOrchestrationIssue({
+        operation: "Mock environment upsert",
+        entity: `workspace ${inputs.workspaceId} environment "${displayName}"`,
+        cause: error,
+        remediation: "verify environment access or disable mock-environment-enabled then rerun",
+        mask
+      })
+    );
+    return "";
+  }
+}
 function ensureDir(path5) {
   (0, import_node_fs5.mkdirSync)(path5, { recursive: true });
 }
@@ -137827,6 +137969,13 @@ async function exportArtifacts(inputs, dependencies, envUids, assetProjectName,
       true
     );
   }
+  if (options.mockEnvironmentUid) {
+    writeJsonFile(
+      `${mocksDir}/manual-validation.postman_environment.json`,
+      await dependencies.postman.getEnvironment(options.mockEnvironmentUid),
+      true
+    );
+  }
   const durableWorkspaceId = resolveDurableWorkspaceId({
     candidateId: inputs.workspaceId,
     priorId: options.priorWorkspaceId,
@@ -137885,7 +138034,11 @@ function createRepoSummary(outputs, envUids, pushed) {
     commitSha: outputs["commit-sha"],
     environmentCount: Object.keys(envUids).length,
     environmentSyncStatus: outputs["environment-sync-status"],
+    mockEnvironmentStatus: outputs["mock-environment-status"],
+    mockEnvironmentUid: outputs["mock-environment-uid"],
+    mockAuthRequired: outputs["mock-auth-required"] === "true",
     mockUrl: outputs["mock-url"],
+    mockVisibility: outputs["mock-visibility"],
     monitorId: outputs["monitor-id"],
     pushed,
     resolvedCurrentRef: outputs["resolved-current-ref"],
@@ -138113,6 +138266,7 @@ async function runRepoSyncInner(inputs, dependencies) {
     const mockEnvUid = envUids.dev || envUids.prod || Object.values(envUids)[0];
     if (mockEnvUid) {
       let resolvedMockUrl = "";
+      let resolvedMockVisibility = "";
       const mockName = `${assetProjectName} Mock`;
       if (inputs.mockUrl) {
         let mocks;
@@ -138130,12 +138284,15 @@ async function runRepoSyncInner(inputs, dependencies) {
             { cause: error }
           );
         }
-        resolvedMockUrl = resolveExplicitPublicMock(
+        const resolved = resolveExplicitMock(
           mocks,
           inputs.mockUrl,
           inputs.baselineCollectionId,
-          mockEnvUid
-        ).mockUrl;
+          mockEnvUid,
+          inputs.mockVisibility
+        );
+        resolvedMockUrl = resolved.mockUrl;
+        resolvedMockVisibility = resolved.visibility;
         dependencies.core.info(`Reusing mock from explicit input: ${resolvedMockUrl}`);
       }
       if (!resolvedMockUrl && inputs.baselineCollectionId) {
@@ -138159,7 +138316,9 @@ async function runRepoSyncInner(inputs, dependencies) {
           );
         }
         if (discovered) {
-          resolvedMockUrl = requirePublicMock(discovered).mockUrl;
+          const resolved = requireMockVisibility(discovered, inputs.mockVisibility);
+          resolvedMockUrl = resolved.mockUrl;
+          resolvedMockVisibility = resolved.visibility;
           dependencies.core.info(`Discovered existing mock for collection ${inputs.baselineCollectionId}: ${resolvedMockUrl}`);
         }
       }
@@ -138172,7 +138331,8 @@ async function runRepoSyncInner(inputs, dependencies) {
               inputs.workspaceId,
               mockName,
               inputs.baselineCollectionId,
-              mockEnvUid
+              mockEnvUid,
+              inputs.mockVisibility
             ),
             {
               maxAttempts: 3,
@@ -138194,6 +138354,7 @@ async function runRepoSyncInner(inputs, dependencies) {
             }
           );
           resolvedMockUrl = mock.url;
+          resolvedMockVisibility = mock.visibility ?? inputs.mockVisibility;
           dependencies.core.info(`Created new mock: ${resolvedMockUrl}`);
         } catch (error) {
           throw new Error(
@@ -138209,7 +138370,37 @@ async function runRepoSyncInner(inputs, dependencies) {
         }
       }
       outputs["mock-url"] = resolvedMockUrl;
+      outputs["mock-visibility"] = resolvedMockVisibility;
+      outputs["mock-auth-required"] = String(resolvedMockVisibility === "private");
       dependencies.core.setOutput("mock-url", resolvedMockUrl);
+      dependencies.core.setOutput("mock-visibility", resolvedMockVisibility);
+      dependencies.core.setOutput("mock-auth-required", outputs["mock-auth-required"]);
+      if (resolvedMockVisibility === "private") {
+        if (!dependencies.postman.configurePrivateMockRuntimeAuth) {
+          throw new Error(
+            "PRIVATE_MOCK_RUNTIME_AUTH_UNAVAILABLE: The Postman client cannot configure runtime x-api-key injection."
+          );
+        }
+        for (const collectionUid of [inputs.smokeCollectionId, inputs.contractCollectionId]) {
+          if (collectionUid) {
+            await dependencies.postman.configurePrivateMockRuntimeAuth(collectionUid);
+          }
+        }
+      }
+      if (inputs.mockEnvironmentEnabled && isCanonicalWriter) {
+        const mockEnvironmentUid = await upsertMockEnvironment(
+          inputs,
+          dependencies,
+          assetProjectName,
+          resolvedMockUrl
+        );
+        outputs["mock-environment-uid"] = mockEnvironmentUid;
+        outputs["mock-environment-status"] = mockEnvironmentUid ? "success" : "failed";
+      } else if (inputs.mockEnvironmentEnabled) {
+        dependencies.core.warning(
+          "mock-environment-enabled is skipped for preview and channel runs so manual-validation environments cannot escape branch retention cleanup."
+        );
+      }
     }
   }
   if (inputs.workspaceId && inputs.smokeCollectionId && Object.keys(envUids).length > 0) {
@@ -138342,6 +138533,7 @@ async function runRepoSyncInner(inputs, dependencies) {
     workspaceLinkStatus: outputs["workspace-link-status"],
     priorWorkspaceId: resourcesState?.workspace?.id,
     existingSpecs: resourcesState?.cloudResources?.specs,
+    mockEnvironmentUid: outputs["mock-environment-uid"] || void 0,
     releaseLabel,
     priorState: resourcesState,
     preparedPrebuiltCollections
@@ -139162,6 +139354,8 @@ var CLI_INPUT_NAMES = [
   "org-mode",
   "monitor-id",
   "mock-url",
+  "mock-visibility",
+  "mock-environment-enabled",
   "monitor-cron",
   "ssl-client-cert",
   "ssl-client-key",