@postman-cse/onboarding-repo-sync 2.1.18 → 2.2.0

package/README.md

@@ -113,6 +113,17 @@ with:
   monitor-id: 1e2f3a4b-monitor-id
 ```
 
+Repo-sync supports public mocks for anonymous validation. An explicit `mock-url` must match one mock in the resolved workspace and reference the expected baseline collection and environment. Discovered and newly created mocks pass the same live visibility check. Private mocks, responses without a recognized visibility field, stale URLs, and identity mismatches fail before `mock-url` is emitted; repo-sync never places a Postman API key in a collection or environment to make a private mock callable.
+
+For manual collection validation against that public mock, opt in to a dedicated Postman environment:
+
+```yaml
+with:
+  mock-environment-enabled: true
+```
+
+On canonical and legacy runs, the action creates or reuses `<project> - Mock`, sets its `baseUrl` to the validated mock URL, and emits `mock-environment-uid`. Preview and channel runs skip it so branch retention cleanup cannot leak an untracked environment. Its exported representation lives at `postman/mocks/manual-validation.postman_environment.json`; it is deliberately excluded from `environment-uids-json`, system-environment associations, monitors, and generated CI environment selection. Select it explicitly when running baseline, Smoke, or Contract collections manually. Repo-sync never replaces the runtime `prod` or `dev` `baseUrl` with a mock URL.
+
 ### mTLS certificates for Postman CLI runs
 
 The generated CI workflow can run [Postman CLI collection runs](https://learning.postman.com/docs/postman-cli/postman-cli-collections/) with client certificates. Pass the cert material as inputs; when a GitHub token and repository context are available, the action persists them as repository secrets (`POSTMAN_SSL_CLIENT_CERT_B64`, `POSTMAN_SSL_CLIENT_KEY_B64`, `POSTMAN_SSL_CLIENT_PASSPHRASE`, `POSTMAN_SSL_EXTRA_CA_CERTS_B64`) for the generated workflow:
@@ -144,6 +155,7 @@ with:
 | `release-label` | Optional release label used for versioned naming. | no |  |
 | `monitor-id` | Existing smoke monitor ID. When set, the action validates and reuses this monitor instead of creating a new one. | no |  |
 | `mock-url` | Existing mock server URL. When set, the action validates and reuses this mock instead of creating a new one. | no |  |
+| `mock-environment-enabled` | Create or update a dedicated manual-validation environment whose baseUrl is the validated public mock URL. This environment is excluded from runtime CI selection. | no | `false` |
 | `monitor-cron` | 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). | no | `""` |
 | `environments-json` | JSON array of environment slugs to create or update. | no | `["prod"]` |
 | `git-provider` | Git provider override ('github', 'gitlab', 'bitbucket', 'azure-devops'). Auto-detected from environment when omitted. | no |  |
@@ -191,6 +203,8 @@ with:
 | `environment-sync-status` | Whether environment sync succeeded, was skipped, or failed. |
 | `environment-uids-json` | JSON map of environment slug to Postman environment uid. |
 | `mock-url` | Created or reused mock server URL. |
+| `mock-environment-uid` | Dedicated manual-validation environment UID when mock-environment-enabled succeeds. |
+| `mock-environment-status` | Whether the optional manual-validation mock environment succeeded, was skipped, or failed. |
 | `monitor-id` | Created or reused smoke monitor ID. |
 | `repo-sync-summary-json` | JSON summary of repo materialization and workspace sync outputs. |
 | `commit-sha` | Commit SHA produced by repo-write-mode, if any. |
@@ -283,7 +297,7 @@ For `commit-and-push`, the push target is resolved from `current-ref`, then `GIT
 
 Mocks and monitors: when `baseline-collection-id`, `workspace-id`, and at least one environment are available, the action creates or reuses a mock server. When `smoke-collection-id` is also available, it creates or reuses a cloud smoke monitor unless `monitor-type: cli` is set. With an empty `monitor-cron`, a new cloud monitor is created disabled and triggered once per workflow invocation.
 
-Asset reuse priority is explicit inputs (`environment-uids-json`, `mock-url`, `monitor-id`), then live discovery by exact workspace-scoped name, collection UID, and environment UID, then create. Creates submit once and reconcile on ambiguous gateway errors; overlapping compatible creates inside one process share a single in-flight promise. Adopted environments are updated to the requested values. Mock environment assignment has no verified patch route, so a mock is reused only when its live environment already matches; mismatches are never claimed as converged. Concurrent jobs against the same workspace can still race because Postman does not expose create idempotency keys—serialize those workflows with GitHub Actions `concurrency` (or an equivalent CI lock) when duplicate mocks/monitors/environments would be harmful.
+Asset reuse priority is explicit inputs (`environment-uids-json`, `mock-url`, `monitor-id`), then live discovery by exact workspace-scoped name, collection UID, and environment UID, then create. Mock reuse is public-only: the gateway's live `published` field must confirm public visibility, and explicit URLs must match the expected workspace, collection, and environment. Private or unknown visibility fails closed without injecting credentials. Creates submit once and reconcile on ambiguous gateway errors; overlapping compatible creates inside one process share a single in-flight promise. Adopted environments are updated to the requested values. Mock environment assignment has no verified patch route, so a mock is reused only when its live environment already matches; mismatches are never claimed as converged. Concurrent jobs against the same workspace can still race because Postman does not expose create idempotency keys—serialize those workflows with GitHub Actions `concurrency` (or an equivalent CI lock) when duplicate mocks/monitors/environments would be harmful.
 
 Deeper reference:
 

package/action.yml

@@ -57,6 +57,10 @@ inputs:
   mock-url:
     description: Existing mock server URL. When set, the action validates and reuses this mock instead of creating a new one.
     required: false
+  mock-environment-enabled:
+    description: Create or update a dedicated manual-validation environment whose baseUrl is the validated public mock URL. This environment is excluded from runtime CI selection.
+    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
@@ -200,6 +204,10 @@ outputs:
     description: JSON map of environment slug to Postman environment uid.
   mock-url:
     description: Created or reused mock server URL.
+  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.
   repo-sync-summary-json:

package/dist/action.cjs

@@ -136660,6 +136660,11 @@ 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-environment-enabled": {
+      description: "Create or update a dedicated manual-validation environment whose baseUrl is the validated public mock URL. This environment is excluded from runtime CI selection.",
+      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,
@@ -136853,6 +136858,12 @@ var postmanRepoSyncActionContract = {
     "mock-url": {
       description: "Created or reused mock server URL."
     },
+    "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."
     },
@@ -136941,6 +136952,25 @@ var PostmanAssetsClient = class {
 };
 
 // src/lib/postman/postman-gateway-assets-client.ts
+var MockContractError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "MockContractError";
+  }
+};
+function requirePublicMock(mock) {
+  if (mock.visibility === "private") {
+    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.`
+    );
+  }
+  if (mock.visibility !== "public") {
+    throw new MockContractError(
+      `MOCK_VISIBILITY_UNKNOWN: Mock ${mock.uid} did not expose a supported visibility field. Refusing to assume it is publicly callable.`
+    );
+  }
+  return mock;
+}
 var MAX_CREATE_FLIGHTS = 256;
 var createFlights = /* @__PURE__ */ new Map();
 var PostmanGatewayAssetsClient = class {
@@ -137122,6 +137152,41 @@ var PostmanGatewayAssetsClient = class {
     const id = record.uid ?? record.id;
     return typeof id === "string" ? id.trim() : String(id ?? "").trim();
   }
+  decodeMockRecord(value, operation) {
+    const record = this.asRecord(value);
+    if (!record) {
+      throw new MockContractError(
+        `CONTRACT_MOCK_RESPONSE_INVALID: ${operation} returned a non-object mock record`
+      );
+    }
+    const uid = this.idOf(record);
+    const name = typeof record.name === "string" ? record.name.trim() : "";
+    const collection = typeof record.collection === "string" ? record.collection.trim() : "";
+    const mockUrl = typeof (record.url ?? record.mockUrl) === "string" ? String(record.url ?? record.mockUrl).trim() : "";
+    const environment = typeof record.environment === "string" ? record.environment.trim() : "";
+    if (!uid) {
+      throw new MockContractError(
+        `CONTRACT_MOCK_RESPONSE_INVALID: ${operation} returned a mock without a UID`
+      );
+    }
+    if (!name) {
+      throw new MockContractError(
+        `CONTRACT_MOCK_RESPONSE_INVALID: ${operation} returned mock ${uid} without a name`
+      );
+    }
+    if (!collection) {
+      throw new MockContractError(
+        `CONTRACT_MOCK_RESPONSE_INVALID: ${operation} returned mock ${uid} without a collection UID`
+      );
+    }
+    if (!mockUrl) {
+      throw new MockContractError(
+        `CONTRACT_MOCK_RESPONSE_INVALID: ${operation} returned mock ${uid} without a URL`
+      );
+    }
+    const visibility = typeof record.published === "boolean" ? record.published ? "public" : "private" : "unknown";
+    return { uid, name, collection, mockUrl, environment, visibility };
+  }
   /**
    * Reduce a Postman public uid (`<owner>-<uuid>`, 6 hyphen groups) to the bare
    * model id (`<uuid>`, 5 groups), mirroring `decomposeUID`. Used ONLY for the
@@ -137422,7 +137487,8 @@ var PostmanGatewayAssetsClient = class {
     return this.singleFlight(flightKey, flightKey, "mock", async () => {
       const existing = await this.findMockByCollection(collection, environment, mockName);
       if (existing) {
-        return { uid: existing.uid, url: existing.mockUrl };
+        const reusable = requirePublicMock(existing);
+        return { uid: reusable.uid, url: reusable.mockUrl };
       }
       const body = {
         name: mockName,
@@ -137445,13 +137511,12 @@ var PostmanGatewayAssetsClient = class {
       );
       const parseMock = (response) => {
         const record = this.dataOf(response);
-        const uid = this.idOf(record);
-        if (!uid) {
-          throw new Error("Mock create did not return a UID");
-        }
+        const created = requirePublicMock(
+          this.decodeMockRecord(record, "Mock create")
+        );
         return {
-          uid,
-          url: String(record?.url ?? record?.mockUrl ?? "").trim()
+          uid: created.uid,
+          url: created.mockUrl
         };
       };
       try {
@@ -137462,7 +137527,8 @@ var PostmanGatewayAssetsClient = class {
           error2
         );
         if (adopted) {
-          return { uid: adopted.uid, url: adopted.mockUrl };
+          const reusable = requirePublicMock(adopted);
+          return { uid: reusable.uid, url: reusable.mockUrl };
         }
         if (adopted === void 0) {
           const retried = await this.resendAbsentCreate(async () => parseMock(await send2("auto")));
@@ -137478,14 +137544,14 @@ var PostmanGatewayAssetsClient = class {
       method: "get",
       path: `/mocks?workspace=${this.workspaceId}`
     });
-    const items = Array.isArray(response) ? response : Array.isArray(this.asRecord(response)?.data) ? this.asRecord(response).data : [];
-    return items.map((raw) => this.asRecord(raw)).filter((m) => m !== null).map((m) => ({
-      uid: this.idOf(m),
-      name: String(m.name ?? ""),
-      collection: String(m.collection ?? ""),
-      mockUrl: String(m.url ?? m.mockUrl ?? ""),
-      environment: String(m.environment ?? "")
-    }));
+    const envelope = this.asRecord(response);
+    const items = Array.isArray(response) ? response : Array.isArray(envelope?.data) ? envelope.data : null;
+    if (!items) {
+      throw new MockContractError(
+        "CONTRACT_MOCK_RESPONSE_INVALID: Mock list envelope must be an array or contain a data array"
+      );
+    }
+    return items.map((raw) => this.decodeMockRecord(raw, "Mock list"));
   }
   /**
    * Delete an environment through the sync service (GC path). The path id is
@@ -137539,7 +137605,7 @@ var PostmanGatewayAssetsClient = class {
       `workspace ${this.workspaceId}, name "${mockName}", collection ${want}, and environment ${environment || "(none)"}`,
       matches
     );
-    return match ? { uid: match.uid, mockUrl: match.mockUrl } : null;
+    return match;
   }
   // --- monitors (service: monitors; collection-based = jobTemplates) ---
   /** Map raw jobTemplate records to the facade shape; `collection` is a flat public uid. */
@@ -138469,6 +138535,61 @@ function resolveRepoSyncMasker(dependencies) {
 function causeText(cause) {
   return cause instanceof Error ? cause.message : String(cause);
 }
+function normalizeMockUrl(value, source) {
+  let url;
+  try {
+    url = new URL(String(value || "").trim());
+  } catch {
+    throw new MockContractError(
+      `EXPLICIT_MOCK_URL_INVALID: ${source} is not a valid absolute URL`
+    );
+  }
+  if (url.protocol !== "https:" || url.username || url.password || url.search || url.hash) {
+    throw new MockContractError(
+      `EXPLICIT_MOCK_URL_INVALID: ${source} must be an HTTPS URL without credentials, query parameters, or a fragment`
+    );
+  }
+  url.pathname = url.pathname.replace(/\/+$/g, "") || "/";
+  return url.toString();
+}
+function resolveExplicitPublicMock(mocks, explicitUrl, collectionUid, environmentUid) {
+  const normalized = normalizeMockUrl(explicitUrl, "mock-url");
+  const matches = mocks.filter(
+    (mock) => normalizeMockUrl(mock.mockUrl, `mock ${mock.uid} URL`) === normalized
+  );
+  if (matches.length === 0) {
+    throw new MockContractError(
+      `EXPLICIT_MOCK_URL_NOT_FOUND: mock-url was not found in the resolved workspace mock inventory`
+    );
+  }
+  if (matches.length > 1) {
+    throw new MockContractError(
+      `EXPLICIT_MOCK_URL_AMBIGUOUS: mock-url matched multiple workspace mocks (${matches.map((mock) => mock.uid).join(", ")})`
+    );
+  }
+  const match = matches[0];
+  if (match.collection !== collectionUid) {
+    throw new MockContractError(
+      `EXPLICIT_MOCK_IDENTITY_MISMATCH: Mock ${match.uid} references collection ${match.collection || "(none)"}, expected ${collectionUid}`
+    );
+  }
+  if (match.environment !== environmentUid) {
+    throw new MockContractError(
+      `EXPLICIT_MOCK_IDENTITY_MISMATCH: Mock ${match.uid} references environment ${match.environment || "(none)"}, expected ${environmentUid}`
+    );
+  }
+  return requirePublicMock(match);
+}
+function shouldRetryMockCreate(error2) {
+  if (error2 instanceof MockContractError) return false;
+  if (error2 instanceof HttpError) {
+    return error2.status === 408 || error2.status === 429 || error2.status >= 500;
+  }
+  if (error2 instanceof Error && error2.message.startsWith("Multiple mocks match ")) {
+    return false;
+  }
+  return true;
+}
 function toOneLineDisplay(value) {
   return String(value ?? "").replace(/[\r\n\u0085\u2028\u2029\v\f]+/g, " ").replace(/[ \t]{2,}/g, " ").trim();
 }
@@ -138675,6 +138796,7 @@ function resolveInputs(env = process.env) {
     orgMode: parseBooleanInput(getInput2("org-mode", env), false),
     monitorId: getInput2("monitor-id", env),
     mockUrl: getInput2("mock-url", env),
+    mockEnvironmentEnabled: parseBooleanInput(getInput2("mock-environment-enabled", env), false),
     monitorCron: getInput2("monitor-cron", env),
     sslClientCert: getInput2("ssl-client-cert", env),
     sslClientKey: getInput2("ssl-client-key", env),
@@ -138901,6 +139023,8 @@ function createOutputs(inputs) {
     "environment-sync-status": "skipped",
     "environment-uids-json": JSON.stringify(inputs.environmentUids),
     "mock-url": "",
+    "mock-environment-uid": "",
+    "mock-environment-status": "skipped",
     "monitor-id": "",
     "repo-sync-summary-json": "{}",
     "commit-sha": "",
@@ -138968,6 +139092,7 @@ function readActionInputs(actionCore) {
     INPUT_ORG_MODE: readInput(actionCore, "org-mode"),
     INPUT_MONITOR_ID: readInput(actionCore, "monitor-id"),
     INPUT_MOCK_URL: readInput(actionCore, "mock-url"),
+    INPUT_MOCK_ENVIRONMENT_ENABLED: readInput(actionCore, "mock-environment-enabled"),
     INPUT_MONITOR_CRON: readInput(actionCore, "monitor-cron"),
     INPUT_SSL_CLIENT_CERT: sslClientCert,
     INPUT_SSL_CLIENT_KEY: sslClientKey,
@@ -139169,6 +139294,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 (error2) {
+    dependencies.core.warning(
+      formatOrchestrationIssue({
+        operation: "Mock environment upsert",
+        entity: `workspace ${inputs.workspaceId} environment "${displayName}"`,
+        cause: error2,
+        remediation: "verify environment access or disable mock-environment-enabled then rerun",
+        mask
+      })
+    );
+    return "";
+  }
+}
 function ensureDir(path9) {
   (0, import_node_fs5.mkdirSync)(path9, { recursive: true });
 }
@@ -139807,6 +139978,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,
@@ -139865,6 +140043,8 @@ 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"],
     mockUrl: outputs["mock-url"],
     monitorId: outputs["monitor-id"],
     pushed,
@@ -140095,20 +140275,37 @@ async function runRepoSyncInner(inputs, dependencies) {
       let resolvedMockUrl = "";
       const mockName = `${assetProjectName} Mock`;
       if (inputs.mockUrl) {
-        resolvedMockUrl = inputs.mockUrl;
+        let mocks;
+        try {
+          mocks = await dependencies.postman.listMocks();
+        } catch (error2) {
+          throw new Error(
+            formatOrchestrationIssue({
+              operation: "Explicit mock-url lookup",
+              entity: `mock-url ${inputs.mockUrl} workspace ${inputs.workspaceId} collection ${inputs.baselineCollectionId} environment ${mockEnvUid}`,
+              cause: error2,
+              remediation: "verify the URL and mock access then rerun",
+              mask
+            }),
+            { cause: error2 }
+          );
+        }
+        resolvedMockUrl = resolveExplicitPublicMock(
+          mocks,
+          inputs.mockUrl,
+          inputs.baselineCollectionId,
+          mockEnvUid
+        ).mockUrl;
         dependencies.core.info(`Reusing mock from explicit input: ${resolvedMockUrl}`);
       }
       if (!resolvedMockUrl && inputs.baselineCollectionId) {
+        let discovered;
         try {
-          const discovered = await dependencies.postman.findMockByCollection(
+          discovered = await dependencies.postman.findMockByCollection(
             inputs.baselineCollectionId,
             mockEnvUid,
             mockName
           );
-          if (discovered) {
-            resolvedMockUrl = discovered.mockUrl;
-            dependencies.core.info(`Discovered existing mock for collection ${inputs.baselineCollectionId}: ${resolvedMockUrl}`);
-          }
         } catch (error2) {
           throw new Error(
             formatOrchestrationIssue({
@@ -140121,6 +140318,10 @@ async function runRepoSyncInner(inputs, dependencies) {
             { cause: error2 }
           );
         }
+        if (discovered) {
+          resolvedMockUrl = requirePublicMock(discovered).mockUrl;
+          dependencies.core.info(`Discovered existing mock for collection ${inputs.baselineCollectionId}: ${resolvedMockUrl}`);
+        }
       }
       if (!resolvedMockUrl) {
         const mockEntity = `mock "${mockName}" workspace ${inputs.workspaceId} collection ${inputs.baselineCollectionId} environment ${mockEnvUid}`;
@@ -140137,6 +140338,7 @@ async function runRepoSyncInner(inputs, dependencies) {
               maxAttempts: 3,
               delayMs: 2e3,
               backoffMultiplier: 2,
+              shouldRetry: (error2) => shouldRetryMockCreate(error2),
               onRetry: ({ attempt, maxAttempts, error: error2 }) => {
                 dependencies.core.warning(
                   formatOrchestrationIssue({
@@ -140168,6 +140370,20 @@ async function runRepoSyncInner(inputs, dependencies) {
       }
       outputs["mock-url"] = resolvedMockUrl;
       dependencies.core.setOutput("mock-url", resolvedMockUrl);
+      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) {
@@ -140300,6 +140516,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

package/dist/cli.cjs

@@ -134765,6 +134765,11 @@ 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-environment-enabled": {
+      description: "Create or update a dedicated manual-validation environment whose baseUrl is the validated public mock URL. This environment is excluded from runtime CI selection.",
+      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 +134963,12 @@ var postmanRepoSyncActionContract = {
     "mock-url": {
       description: "Created or reused mock server URL."
     },
+    "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."
     },
@@ -135046,6 +135057,25 @@ var PostmanAssetsClient = class {
 };
 
 // src/lib/postman/postman-gateway-assets-client.ts
+var MockContractError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "MockContractError";
+  }
+};
+function requirePublicMock(mock) {
+  if (mock.visibility === "private") {
+    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.`
+    );
+  }
+  if (mock.visibility !== "public") {
+    throw new MockContractError(
+      `MOCK_VISIBILITY_UNKNOWN: Mock ${mock.uid} did not expose a supported visibility field. Refusing to assume it is publicly callable.`
+    );
+  }
+  return mock;
+}
 var MAX_CREATE_FLIGHTS = 256;
 var createFlights = /* @__PURE__ */ new Map();
 var PostmanGatewayAssetsClient = class {
@@ -135227,6 +135257,41 @@ var PostmanGatewayAssetsClient = class {
     const id = record.uid ?? record.id;
     return typeof id === "string" ? id.trim() : String(id ?? "").trim();
   }
+  decodeMockRecord(value, operation) {
+    const record = this.asRecord(value);
+    if (!record) {
+      throw new MockContractError(
+        `CONTRACT_MOCK_RESPONSE_INVALID: ${operation} returned a non-object mock record`
+      );
+    }
+    const uid = this.idOf(record);
+    const name = typeof record.name === "string" ? record.name.trim() : "";
+    const collection = typeof record.collection === "string" ? record.collection.trim() : "";
+    const mockUrl = typeof (record.url ?? record.mockUrl) === "string" ? String(record.url ?? record.mockUrl).trim() : "";
+    const environment = typeof record.environment === "string" ? record.environment.trim() : "";
+    if (!uid) {
+      throw new MockContractError(
+        `CONTRACT_MOCK_RESPONSE_INVALID: ${operation} returned a mock without a UID`
+      );
+    }
+    if (!name) {
+      throw new MockContractError(
+        `CONTRACT_MOCK_RESPONSE_INVALID: ${operation} returned mock ${uid} without a name`
+      );
+    }
+    if (!collection) {
+      throw new MockContractError(
+        `CONTRACT_MOCK_RESPONSE_INVALID: ${operation} returned mock ${uid} without a collection UID`
+      );
+    }
+    if (!mockUrl) {
+      throw new MockContractError(
+        `CONTRACT_MOCK_RESPONSE_INVALID: ${operation} returned mock ${uid} without a URL`
+      );
+    }
+    const visibility = typeof record.published === "boolean" ? record.published ? "public" : "private" : "unknown";
+    return { uid, name, collection, mockUrl, environment, visibility };
+  }
   /**
    * Reduce a Postman public uid (`<owner>-<uuid>`, 6 hyphen groups) to the bare
    * model id (`<uuid>`, 5 groups), mirroring `decomposeUID`. Used ONLY for the
@@ -135527,7 +135592,8 @@ var PostmanGatewayAssetsClient = class {
     return this.singleFlight(flightKey, flightKey, "mock", async () => {
       const existing = await this.findMockByCollection(collection, environment, mockName);
       if (existing) {
-        return { uid: existing.uid, url: existing.mockUrl };
+        const reusable = requirePublicMock(existing);
+        return { uid: reusable.uid, url: reusable.mockUrl };
       }
       const body = {
         name: mockName,
@@ -135550,13 +135616,12 @@ var PostmanGatewayAssetsClient = class {
       );
       const parseMock = (response) => {
         const record = this.dataOf(response);
-        const uid = this.idOf(record);
-        if (!uid) {
-          throw new Error("Mock create did not return a UID");
-        }
+        const created = requirePublicMock(
+          this.decodeMockRecord(record, "Mock create")
+        );
         return {
-          uid,
-          url: String(record?.url ?? record?.mockUrl ?? "").trim()
+          uid: created.uid,
+          url: created.mockUrl
         };
       };
       try {
@@ -135567,7 +135632,8 @@ var PostmanGatewayAssetsClient = class {
           error
         );
         if (adopted) {
-          return { uid: adopted.uid, url: adopted.mockUrl };
+          const reusable = requirePublicMock(adopted);
+          return { uid: reusable.uid, url: reusable.mockUrl };
         }
         if (adopted === void 0) {
           const retried = await this.resendAbsentCreate(async () => parseMock(await send2("auto")));
@@ -135583,14 +135649,14 @@ var PostmanGatewayAssetsClient = class {
       method: "get",
       path: `/mocks?workspace=${this.workspaceId}`
     });
-    const items = Array.isArray(response) ? response : Array.isArray(this.asRecord(response)?.data) ? this.asRecord(response).data : [];
-    return items.map((raw) => this.asRecord(raw)).filter((m) => m !== null).map((m) => ({
-      uid: this.idOf(m),
-      name: String(m.name ?? ""),
-      collection: String(m.collection ?? ""),
-      mockUrl: String(m.url ?? m.mockUrl ?? ""),
-      environment: String(m.environment ?? "")
-    }));
+    const envelope = this.asRecord(response);
+    const items = Array.isArray(response) ? response : Array.isArray(envelope?.data) ? envelope.data : null;
+    if (!items) {
+      throw new MockContractError(
+        "CONTRACT_MOCK_RESPONSE_INVALID: Mock list envelope must be an array or contain a data array"
+      );
+    }
+    return items.map((raw) => this.decodeMockRecord(raw, "Mock list"));
   }
   /**
    * Delete an environment through the sync service (GC path). The path id is
@@ -135644,7 +135710,7 @@ var PostmanGatewayAssetsClient = class {
       `workspace ${this.workspaceId}, name "${mockName}", collection ${want}, and environment ${environment || "(none)"}`,
       matches
     );
-    return match ? { uid: match.uid, mockUrl: match.mockUrl } : null;
+    return match;
   }
   // --- monitors (service: monitors; collection-based = jobTemplates) ---
   /** Map raw jobTemplate records to the facade shape; `collection` is a flat public uid. */
@@ -136522,6 +136588,61 @@ function resolveRepoSyncMasker(dependencies) {
 function causeText(cause) {
   return cause instanceof Error ? cause.message : String(cause);
 }
+function normalizeMockUrl(value, source) {
+  let url;
+  try {
+    url = new URL(String(value || "").trim());
+  } catch {
+    throw new MockContractError(
+      `EXPLICIT_MOCK_URL_INVALID: ${source} is not a valid absolute URL`
+    );
+  }
+  if (url.protocol !== "https:" || url.username || url.password || url.search || url.hash) {
+    throw new MockContractError(
+      `EXPLICIT_MOCK_URL_INVALID: ${source} must be an HTTPS URL without credentials, query parameters, or a fragment`
+    );
+  }
+  url.pathname = url.pathname.replace(/\/+$/g, "") || "/";
+  return url.toString();
+}
+function resolveExplicitPublicMock(mocks, explicitUrl, collectionUid, environmentUid) {
+  const normalized = normalizeMockUrl(explicitUrl, "mock-url");
+  const matches = mocks.filter(
+    (mock) => normalizeMockUrl(mock.mockUrl, `mock ${mock.uid} URL`) === normalized
+  );
+  if (matches.length === 0) {
+    throw new MockContractError(
+      `EXPLICIT_MOCK_URL_NOT_FOUND: mock-url was not found in the resolved workspace mock inventory`
+    );
+  }
+  if (matches.length > 1) {
+    throw new MockContractError(
+      `EXPLICIT_MOCK_URL_AMBIGUOUS: mock-url matched multiple workspace mocks (${matches.map((mock) => mock.uid).join(", ")})`
+    );
+  }
+  const match = matches[0];
+  if (match.collection !== collectionUid) {
+    throw new MockContractError(
+      `EXPLICIT_MOCK_IDENTITY_MISMATCH: Mock ${match.uid} references collection ${match.collection || "(none)"}, expected ${collectionUid}`
+    );
+  }
+  if (match.environment !== environmentUid) {
+    throw new MockContractError(
+      `EXPLICIT_MOCK_IDENTITY_MISMATCH: Mock ${match.uid} references environment ${match.environment || "(none)"}, expected ${environmentUid}`
+    );
+  }
+  return requirePublicMock(match);
+}
+function shouldRetryMockCreate(error) {
+  if (error instanceof MockContractError) return false;
+  if (error instanceof HttpError) {
+    return error.status === 408 || error.status === 429 || error.status >= 500;
+  }
+  if (error instanceof Error && error.message.startsWith("Multiple mocks match ")) {
+    return false;
+  }
+  return true;
+}
 function toOneLineDisplay(value) {
   return String(value ?? "").replace(/[\r\n\u0085\u2028\u2029\v\f]+/g, " ").replace(/[ \t]{2,}/g, " ").trim();
 }
@@ -136725,6 +136846,7 @@ function resolveInputs(env = process.env) {
     orgMode: parseBooleanInput(getInput("org-mode", env), false),
     monitorId: getInput("monitor-id", env),
     mockUrl: getInput("mock-url", 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),
@@ -136951,6 +137073,8 @@ function createOutputs(inputs) {
     "environment-sync-status": "skipped",
     "environment-uids-json": JSON.stringify(inputs.environmentUids),
     "mock-url": "",
+    "mock-environment-uid": "",
+    "mock-environment-status": "skipped",
     "monitor-id": "",
     "repo-sync-summary-json": "{}",
     "commit-sha": "",
@@ -137079,6 +137203,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 });
 }
@@ -137717,6 +137887,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,
@@ -137775,6 +137952,8 @@ 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"],
     mockUrl: outputs["mock-url"],
     monitorId: outputs["monitor-id"],
     pushed,
@@ -138005,20 +138184,37 @@ async function runRepoSyncInner(inputs, dependencies) {
       let resolvedMockUrl = "";
       const mockName = `${assetProjectName} Mock`;
       if (inputs.mockUrl) {
-        resolvedMockUrl = inputs.mockUrl;
+        let mocks;
+        try {
+          mocks = await dependencies.postman.listMocks();
+        } catch (error) {
+          throw new Error(
+            formatOrchestrationIssue({
+              operation: "Explicit mock-url lookup",
+              entity: `mock-url ${inputs.mockUrl} workspace ${inputs.workspaceId} collection ${inputs.baselineCollectionId} environment ${mockEnvUid}`,
+              cause: error,
+              remediation: "verify the URL and mock access then rerun",
+              mask
+            }),
+            { cause: error }
+          );
+        }
+        resolvedMockUrl = resolveExplicitPublicMock(
+          mocks,
+          inputs.mockUrl,
+          inputs.baselineCollectionId,
+          mockEnvUid
+        ).mockUrl;
         dependencies.core.info(`Reusing mock from explicit input: ${resolvedMockUrl}`);
       }
       if (!resolvedMockUrl && inputs.baselineCollectionId) {
+        let discovered;
         try {
-          const discovered = await dependencies.postman.findMockByCollection(
+          discovered = await dependencies.postman.findMockByCollection(
             inputs.baselineCollectionId,
             mockEnvUid,
             mockName
           );
-          if (discovered) {
-            resolvedMockUrl = discovered.mockUrl;
-            dependencies.core.info(`Discovered existing mock for collection ${inputs.baselineCollectionId}: ${resolvedMockUrl}`);
-          }
         } catch (error) {
           throw new Error(
             formatOrchestrationIssue({
@@ -138031,6 +138227,10 @@ async function runRepoSyncInner(inputs, dependencies) {
             { cause: error }
           );
         }
+        if (discovered) {
+          resolvedMockUrl = requirePublicMock(discovered).mockUrl;
+          dependencies.core.info(`Discovered existing mock for collection ${inputs.baselineCollectionId}: ${resolvedMockUrl}`);
+        }
       }
       if (!resolvedMockUrl) {
         const mockEntity = `mock "${mockName}" workspace ${inputs.workspaceId} collection ${inputs.baselineCollectionId} environment ${mockEnvUid}`;
@@ -138047,6 +138247,7 @@ async function runRepoSyncInner(inputs, dependencies) {
               maxAttempts: 3,
               delayMs: 2e3,
               backoffMultiplier: 2,
+              shouldRetry: (error) => shouldRetryMockCreate(error),
               onRetry: ({ attempt, maxAttempts, error }) => {
                 dependencies.core.warning(
                   formatOrchestrationIssue({
@@ -138078,6 +138279,20 @@ async function runRepoSyncInner(inputs, dependencies) {
       }
       outputs["mock-url"] = resolvedMockUrl;
       dependencies.core.setOutput("mock-url", resolvedMockUrl);
+      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) {
@@ -138210,6 +138425,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
@@ -139030,6 +139246,7 @@ var CLI_INPUT_NAMES = [
   "org-mode",
   "monitor-id",
   "mock-url",
+  "mock-environment-enabled",
   "monitor-cron",
   "ssl-client-cert",
   "ssl-client-key",

package/dist/index.cjs

@@ -136682,6 +136682,11 @@ 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-environment-enabled": {
+      description: "Create or update a dedicated manual-validation environment whose baseUrl is the validated public mock URL. This environment is excluded from runtime CI selection.",
+      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,
@@ -136875,6 +136880,12 @@ var postmanRepoSyncActionContract = {
     "mock-url": {
       description: "Created or reused mock server URL."
     },
+    "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."
     },
@@ -136963,6 +136974,25 @@ var PostmanAssetsClient = class {
 };
 
 // src/lib/postman/postman-gateway-assets-client.ts
+var MockContractError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "MockContractError";
+  }
+};
+function requirePublicMock(mock) {
+  if (mock.visibility === "private") {
+    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.`
+    );
+  }
+  if (mock.visibility !== "public") {
+    throw new MockContractError(
+      `MOCK_VISIBILITY_UNKNOWN: Mock ${mock.uid} did not expose a supported visibility field. Refusing to assume it is publicly callable.`
+    );
+  }
+  return mock;
+}
 var MAX_CREATE_FLIGHTS = 256;
 var createFlights = /* @__PURE__ */ new Map();
 var PostmanGatewayAssetsClient = class {
@@ -137144,6 +137174,41 @@ var PostmanGatewayAssetsClient = class {
     const id = record.uid ?? record.id;
     return typeof id === "string" ? id.trim() : String(id ?? "").trim();
   }
+  decodeMockRecord(value, operation) {
+    const record = this.asRecord(value);
+    if (!record) {
+      throw new MockContractError(
+        `CONTRACT_MOCK_RESPONSE_INVALID: ${operation} returned a non-object mock record`
+      );
+    }
+    const uid = this.idOf(record);
+    const name = typeof record.name === "string" ? record.name.trim() : "";
+    const collection = typeof record.collection === "string" ? record.collection.trim() : "";
+    const mockUrl = typeof (record.url ?? record.mockUrl) === "string" ? String(record.url ?? record.mockUrl).trim() : "";
+    const environment = typeof record.environment === "string" ? record.environment.trim() : "";
+    if (!uid) {
+      throw new MockContractError(
+        `CONTRACT_MOCK_RESPONSE_INVALID: ${operation} returned a mock without a UID`
+      );
+    }
+    if (!name) {
+      throw new MockContractError(
+        `CONTRACT_MOCK_RESPONSE_INVALID: ${operation} returned mock ${uid} without a name`
+      );
+    }
+    if (!collection) {
+      throw new MockContractError(
+        `CONTRACT_MOCK_RESPONSE_INVALID: ${operation} returned mock ${uid} without a collection UID`
+      );
+    }
+    if (!mockUrl) {
+      throw new MockContractError(
+        `CONTRACT_MOCK_RESPONSE_INVALID: ${operation} returned mock ${uid} without a URL`
+      );
+    }
+    const visibility = typeof record.published === "boolean" ? record.published ? "public" : "private" : "unknown";
+    return { uid, name, collection, mockUrl, environment, visibility };
+  }
   /**
    * Reduce a Postman public uid (`<owner>-<uuid>`, 6 hyphen groups) to the bare
    * model id (`<uuid>`, 5 groups), mirroring `decomposeUID`. Used ONLY for the
@@ -137444,7 +137509,8 @@ var PostmanGatewayAssetsClient = class {
     return this.singleFlight(flightKey, flightKey, "mock", async () => {
       const existing = await this.findMockByCollection(collection, environment, mockName);
       if (existing) {
-        return { uid: existing.uid, url: existing.mockUrl };
+        const reusable = requirePublicMock(existing);
+        return { uid: reusable.uid, url: reusable.mockUrl };
       }
       const body = {
         name: mockName,
@@ -137467,13 +137533,12 @@ var PostmanGatewayAssetsClient = class {
       );
       const parseMock = (response) => {
         const record = this.dataOf(response);
-        const uid = this.idOf(record);
-        if (!uid) {
-          throw new Error("Mock create did not return a UID");
-        }
+        const created = requirePublicMock(
+          this.decodeMockRecord(record, "Mock create")
+        );
         return {
-          uid,
-          url: String(record?.url ?? record?.mockUrl ?? "").trim()
+          uid: created.uid,
+          url: created.mockUrl
         };
       };
       try {
@@ -137484,7 +137549,8 @@ var PostmanGatewayAssetsClient = class {
           error2
         );
         if (adopted) {
-          return { uid: adopted.uid, url: adopted.mockUrl };
+          const reusable = requirePublicMock(adopted);
+          return { uid: reusable.uid, url: reusable.mockUrl };
         }
         if (adopted === void 0) {
           const retried = await this.resendAbsentCreate(async () => parseMock(await send2("auto")));
@@ -137500,14 +137566,14 @@ var PostmanGatewayAssetsClient = class {
       method: "get",
       path: `/mocks?workspace=${this.workspaceId}`
     });
-    const items = Array.isArray(response) ? response : Array.isArray(this.asRecord(response)?.data) ? this.asRecord(response).data : [];
-    return items.map((raw) => this.asRecord(raw)).filter((m) => m !== null).map((m) => ({
-      uid: this.idOf(m),
-      name: String(m.name ?? ""),
-      collection: String(m.collection ?? ""),
-      mockUrl: String(m.url ?? m.mockUrl ?? ""),
-      environment: String(m.environment ?? "")
-    }));
+    const envelope = this.asRecord(response);
+    const items = Array.isArray(response) ? response : Array.isArray(envelope?.data) ? envelope.data : null;
+    if (!items) {
+      throw new MockContractError(
+        "CONTRACT_MOCK_RESPONSE_INVALID: Mock list envelope must be an array or contain a data array"
+      );
+    }
+    return items.map((raw) => this.decodeMockRecord(raw, "Mock list"));
   }
   /**
    * Delete an environment through the sync service (GC path). The path id is
@@ -137561,7 +137627,7 @@ var PostmanGatewayAssetsClient = class {
       `workspace ${this.workspaceId}, name "${mockName}", collection ${want}, and environment ${environment || "(none)"}`,
       matches
     );
-    return match ? { uid: match.uid, mockUrl: match.mockUrl } : null;
+    return match;
   }
   // --- monitors (service: monitors; collection-based = jobTemplates) ---
   /** Map raw jobTemplate records to the facade shape; `collection` is a flat public uid. */
@@ -138491,6 +138557,61 @@ function resolveRepoSyncMasker(dependencies) {
 function causeText(cause) {
   return cause instanceof Error ? cause.message : String(cause);
 }
+function normalizeMockUrl(value, source) {
+  let url;
+  try {
+    url = new URL(String(value || "").trim());
+  } catch {
+    throw new MockContractError(
+      `EXPLICIT_MOCK_URL_INVALID: ${source} is not a valid absolute URL`
+    );
+  }
+  if (url.protocol !== "https:" || url.username || url.password || url.search || url.hash) {
+    throw new MockContractError(
+      `EXPLICIT_MOCK_URL_INVALID: ${source} must be an HTTPS URL without credentials, query parameters, or a fragment`
+    );
+  }
+  url.pathname = url.pathname.replace(/\/+$/g, "") || "/";
+  return url.toString();
+}
+function resolveExplicitPublicMock(mocks, explicitUrl, collectionUid, environmentUid) {
+  const normalized = normalizeMockUrl(explicitUrl, "mock-url");
+  const matches = mocks.filter(
+    (mock) => normalizeMockUrl(mock.mockUrl, `mock ${mock.uid} URL`) === normalized
+  );
+  if (matches.length === 0) {
+    throw new MockContractError(
+      `EXPLICIT_MOCK_URL_NOT_FOUND: mock-url was not found in the resolved workspace mock inventory`
+    );
+  }
+  if (matches.length > 1) {
+    throw new MockContractError(
+      `EXPLICIT_MOCK_URL_AMBIGUOUS: mock-url matched multiple workspace mocks (${matches.map((mock) => mock.uid).join(", ")})`
+    );
+  }
+  const match = matches[0];
+  if (match.collection !== collectionUid) {
+    throw new MockContractError(
+      `EXPLICIT_MOCK_IDENTITY_MISMATCH: Mock ${match.uid} references collection ${match.collection || "(none)"}, expected ${collectionUid}`
+    );
+  }
+  if (match.environment !== environmentUid) {
+    throw new MockContractError(
+      `EXPLICIT_MOCK_IDENTITY_MISMATCH: Mock ${match.uid} references environment ${match.environment || "(none)"}, expected ${environmentUid}`
+    );
+  }
+  return requirePublicMock(match);
+}
+function shouldRetryMockCreate(error2) {
+  if (error2 instanceof MockContractError) return false;
+  if (error2 instanceof HttpError) {
+    return error2.status === 408 || error2.status === 429 || error2.status >= 500;
+  }
+  if (error2 instanceof Error && error2.message.startsWith("Multiple mocks match ")) {
+    return false;
+  }
+  return true;
+}
 function toOneLineDisplay(value) {
   return String(value ?? "").replace(/[\r\n\u0085\u2028\u2029\v\f]+/g, " ").replace(/[ \t]{2,}/g, " ").trim();
 }
@@ -138697,6 +138818,7 @@ function resolveInputs(env = process.env) {
     orgMode: parseBooleanInput(getInput2("org-mode", env), false),
     monitorId: getInput2("monitor-id", env),
     mockUrl: getInput2("mock-url", env),
+    mockEnvironmentEnabled: parseBooleanInput(getInput2("mock-environment-enabled", env), false),
     monitorCron: getInput2("monitor-cron", env),
     sslClientCert: getInput2("ssl-client-cert", env),
     sslClientKey: getInput2("ssl-client-key", env),
@@ -138923,6 +139045,8 @@ function createOutputs(inputs) {
     "environment-sync-status": "skipped",
     "environment-uids-json": JSON.stringify(inputs.environmentUids),
     "mock-url": "",
+    "mock-environment-uid": "",
+    "mock-environment-status": "skipped",
     "monitor-id": "",
     "repo-sync-summary-json": "{}",
     "commit-sha": "",
@@ -138990,6 +139114,7 @@ function readActionInputs(actionCore) {
     INPUT_ORG_MODE: readInput(actionCore, "org-mode"),
     INPUT_MONITOR_ID: readInput(actionCore, "monitor-id"),
     INPUT_MOCK_URL: readInput(actionCore, "mock-url"),
+    INPUT_MOCK_ENVIRONMENT_ENABLED: readInput(actionCore, "mock-environment-enabled"),
     INPUT_MONITOR_CRON: readInput(actionCore, "monitor-cron"),
     INPUT_SSL_CLIENT_CERT: sslClientCert,
     INPUT_SSL_CLIENT_KEY: sslClientKey,
@@ -139191,6 +139316,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 (error2) {
+    dependencies.core.warning(
+      formatOrchestrationIssue({
+        operation: "Mock environment upsert",
+        entity: `workspace ${inputs.workspaceId} environment "${displayName}"`,
+        cause: error2,
+        remediation: "verify environment access or disable mock-environment-enabled then rerun",
+        mask
+      })
+    );
+    return "";
+  }
+}
 function ensureDir(path9) {
   (0, import_node_fs5.mkdirSync)(path9, { recursive: true });
 }
@@ -139829,6 +140000,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,
@@ -139887,6 +140065,8 @@ 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"],
     mockUrl: outputs["mock-url"],
     monitorId: outputs["monitor-id"],
     pushed,
@@ -140117,20 +140297,37 @@ async function runRepoSyncInner(inputs, dependencies) {
       let resolvedMockUrl = "";
       const mockName = `${assetProjectName} Mock`;
       if (inputs.mockUrl) {
-        resolvedMockUrl = inputs.mockUrl;
+        let mocks;
+        try {
+          mocks = await dependencies.postman.listMocks();
+        } catch (error2) {
+          throw new Error(
+            formatOrchestrationIssue({
+              operation: "Explicit mock-url lookup",
+              entity: `mock-url ${inputs.mockUrl} workspace ${inputs.workspaceId} collection ${inputs.baselineCollectionId} environment ${mockEnvUid}`,
+              cause: error2,
+              remediation: "verify the URL and mock access then rerun",
+              mask
+            }),
+            { cause: error2 }
+          );
+        }
+        resolvedMockUrl = resolveExplicitPublicMock(
+          mocks,
+          inputs.mockUrl,
+          inputs.baselineCollectionId,
+          mockEnvUid
+        ).mockUrl;
         dependencies.core.info(`Reusing mock from explicit input: ${resolvedMockUrl}`);
       }
       if (!resolvedMockUrl && inputs.baselineCollectionId) {
+        let discovered;
         try {
-          const discovered = await dependencies.postman.findMockByCollection(
+          discovered = await dependencies.postman.findMockByCollection(
             inputs.baselineCollectionId,
             mockEnvUid,
             mockName
           );
-          if (discovered) {
-            resolvedMockUrl = discovered.mockUrl;
-            dependencies.core.info(`Discovered existing mock for collection ${inputs.baselineCollectionId}: ${resolvedMockUrl}`);
-          }
         } catch (error2) {
           throw new Error(
             formatOrchestrationIssue({
@@ -140143,6 +140340,10 @@ async function runRepoSyncInner(inputs, dependencies) {
             { cause: error2 }
           );
         }
+        if (discovered) {
+          resolvedMockUrl = requirePublicMock(discovered).mockUrl;
+          dependencies.core.info(`Discovered existing mock for collection ${inputs.baselineCollectionId}: ${resolvedMockUrl}`);
+        }
       }
       if (!resolvedMockUrl) {
         const mockEntity = `mock "${mockName}" workspace ${inputs.workspaceId} collection ${inputs.baselineCollectionId} environment ${mockEnvUid}`;
@@ -140159,6 +140360,7 @@ async function runRepoSyncInner(inputs, dependencies) {
               maxAttempts: 3,
               delayMs: 2e3,
               backoffMultiplier: 2,
+              shouldRetry: (error2) => shouldRetryMockCreate(error2),
               onRetry: ({ attempt, maxAttempts, error: error2 }) => {
                 dependencies.core.warning(
                   formatOrchestrationIssue({
@@ -140190,6 +140392,20 @@ async function runRepoSyncInner(inputs, dependencies) {
       }
       outputs["mock-url"] = resolvedMockUrl;
       dependencies.core.setOutput("mock-url", resolvedMockUrl);
+      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) {
@@ -140322,6 +140538,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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@postman-cse/onboarding-repo-sync",
-  "version": "2.1.18",
+  "version": "2.2.0",
   "description": "Postman repo sync GitHub Action.",
   "type": "module",
   "main": "dist/index.cjs",