@postman-cse/onboarding-insights 2.1.0 → 2.1.2

package/dist/cli.cjs

@@ -1,3 +1,4 @@
+#!/usr/bin/env node
 "use strict";
 var __create = Object.create;
 var __defProp = Object.defineProperty;
@@ -18685,10 +18686,145 @@ __export(cli_exports, {
   toDotenv: () => toDotenv
 });
 module.exports = __toCommonJS(cli_exports);
+var import_node_crypto2 = require("node:crypto");
 var import_node_fs2 = require("node:fs");
 var import_promises = require("node:fs/promises");
 var import_node_path2 = __toESM(require("node:path"), 1);
 
+// src/lib/secrets.ts
+var REDACTED = "[REDACTED]";
+var SENSITIVE_HEADER_NAMES = /* @__PURE__ */ new Set([
+  "authorization",
+  "cookie",
+  "proxy-authorization",
+  "set-cookie",
+  "x-access-token",
+  "x-api-key"
+]);
+function isIterable(value) {
+  return value !== null && value !== void 0 && typeof value !== "string" && typeof value[Symbol.iterator] === "function";
+}
+function appendSecretValues(value, results) {
+  if (value === null || value === void 0) {
+    return;
+  }
+  if (typeof value === "string") {
+    const normalized = value.trim();
+    if (normalized) {
+      results.push(normalized);
+    }
+    return;
+  }
+  if (typeof value === "number" || typeof value === "boolean") {
+    results.push(String(value));
+    return;
+  }
+  if (Array.isArray(value) || isIterable(value)) {
+    for (const entry of value) {
+      appendSecretValues(entry, results);
+    }
+  }
+}
+function normalizeSecretValues(secretValues) {
+  const values = [];
+  appendSecretValues(secretValues, values);
+  return [...new Set(values)].sort((left, right) => right.length - left.length);
+}
+function redactSecrets(input, secretValues, replacement = REDACTED) {
+  const source = String(input ?? "");
+  const secrets = normalizeSecretValues(secretValues);
+  if (!source || secrets.length === 0) {
+    return source;
+  }
+  return secrets.reduce((sanitized, secret) => {
+    if (!secret) {
+      return sanitized;
+    }
+    return sanitized.split(secret).join(replacement);
+  }, source);
+}
+function createSecretMasker(secretValues, replacement = REDACTED) {
+  return (input) => redactSecrets(input, secretValues, replacement);
+}
+function headerEntries(headers) {
+  if (headers instanceof Headers) {
+    return Array.from(headers.entries());
+  }
+  if (Array.isArray(headers)) {
+    return headers.map(([name, value]) => [name, String(value)]);
+  }
+  return Object.entries(headers).map(([name, value]) => [name, String(value)]);
+}
+function sanitizeHeaders(headers, secretValues) {
+  if (!headers) {
+    return {};
+  }
+  const sanitized = {};
+  for (const [name, value] of headerEntries(headers)) {
+    const normalizedName = name.toLowerCase();
+    sanitized[normalizedName] = SENSITIVE_HEADER_NAMES.has(normalizedName) ? REDACTED : redactSecrets(value, secretValues);
+  }
+  return sanitized;
+}
+
+// src/lib/http-error.ts
+function truncate(value, limit) {
+  if (value.length <= limit) {
+    return value;
+  }
+  return `${value.slice(0, limit)}...[truncated]`;
+}
+function buildMessage(init) {
+  const method = String(init.method || "GET").toUpperCase();
+  const status = `${init.status}${init.statusText ? ` ${init.statusText}` : ""}`;
+  const url = redactSecrets(init.url, init.secretValues);
+  const body = truncate(
+    redactSecrets(init.responseBody || "", init.secretValues),
+    Math.max(0, init.bodyLimit ?? 800)
+  );
+  return body ? `${method} ${url} failed: ${status} - ${body}` : `${method} ${url} failed: ${status}`;
+}
+var HttpError = class _HttpError extends Error {
+  method;
+  requestHeaders;
+  responseBody;
+  secretValues;
+  status;
+  statusText;
+  url;
+  constructor(init) {
+    super(buildMessage(init));
+    this.name = "HttpError";
+    this.method = String(init.method || "GET").toUpperCase();
+    this.requestHeaders = init.requestHeaders;
+    this.responseBody = init.responseBody || "";
+    this.secretValues = init.secretValues;
+    this.status = init.status;
+    this.statusText = init.statusText;
+    this.url = init.url;
+  }
+  static async fromResponse(response, init) {
+    const responseBody = init.responseBody ?? await response.text().catch(() => "");
+    return new _HttpError({
+      ...init,
+      responseBody,
+      status: response.status,
+      statusText: response.statusText
+    });
+  }
+  toJSON() {
+    return {
+      method: this.method,
+      name: this.name,
+      requestHeaders: sanitizeHeaders(this.requestHeaders, this.secretValues),
+      responseBody: redactSecrets(this.responseBody, this.secretValues),
+      status: this.status,
+      statusText: this.statusText,
+      url: redactSecrets(this.url, this.secretValues)
+    };
+  }
+};
+
 // src/lib/retry.ts
 function sleep(delayMs) {
   return new Promise((resolve2) => {
@@ -18735,6 +18871,42 @@ async function retry(operation, options = {}) {
   }
   throw new Error("Retry exhausted without returning or throwing");
 }
+function isTransientHttpStatus(status) {
+  return status === 408 || status === 429 || status >= 500;
+}
+function extractStatus(error2) {
+  if (error2 instanceof HttpError) {
+    return error2.status;
+  }
+  if (error2 && typeof error2 === "object" && "status" in error2) {
+    const status = error2.status;
+    return typeof status === "number" ? status : void 0;
+  }
+  if (error2 && typeof error2 === "object" && "cause" in error2) {
+    return extractStatus(error2.cause);
+  }
+  return void 0;
+}
+function shouldRetryReadError(error2) {
+  const status = extractStatus(error2);
+  if (status === void 0) {
+    return true;
+  }
+  return isTransientHttpStatus(status);
+}
+function isAmbiguousMutationFailure(error2) {
+  const status = extractStatus(error2);
+  if (status === void 0) {
+    return true;
+  }
+  return isTransientHttpStatus(status);
+}
+var SAFE_READ_RETRY = {
+  maxAttempts: 3,
+  delayMs: 2e3,
+  backoffMultiplier: 2,
+  shouldRetry: (error2) => shouldRetryReadError(error2)
+};
 
 // src/lib/postman/base-urls.ts
 var POSTMAN_ENDPOINT_PROFILES = {
@@ -21625,188 +21797,76 @@ function adviseFromBifrostBody(status, body, ctx) {
   });
 }
 
-// src/lib/secrets.ts
-var REDACTED = "[REDACTED]";
-var SENSITIVE_HEADER_NAMES = /* @__PURE__ */ new Set([
-  "authorization",
-  "cookie",
-  "proxy-authorization",
-  "set-cookie",
-  "x-access-token",
-  "x-api-key"
-]);
-function isIterable(value) {
-  return value !== null && value !== void 0 && typeof value !== "string" && typeof value[Symbol.iterator] === "function";
+// src/lib/bifrost-client.ts
+var DEFAULT_BIFROST_BASE_URL = POSTMAN_ENDPOINT_PROFILES.prod.bifrostBaseUrl;
+var BIFROST_PROXY_PATH = "/ws/proxy";
+var DEFAULT_OBSERVABILITY_BASE_URL = POSTMAN_ENDPOINT_PROFILES.prod.observabilityBaseUrl;
+var DEFAULT_OBSERVABILITY_ENV = POSTMAN_ENDPOINT_PROFILES.prod.observabilityEnv;
+var MAX_DISCOVERED_SERVICE_PAGES = 100;
+var MAX_PROVIDER_SERVICE_PAGES = 100;
+function isExpiredAuthError(status, body) {
+  return status === 401 || body.includes("UNAUTHENTICATED") || body.includes("authenticationError");
 }
-function appendSecretValues(value, results) {
-  if (value === null || value === void 0) {
-    return;
+function normalizeRepoUrl(url) {
+  return url.trim().replace(/\/+$/, "").toLowerCase();
+}
+async function mutateOnceThenReconcile(options) {
+  const existing = await options.findExisting();
+  if (existing !== null) {
+    return existing;
   }
-  if (typeof value === "string") {
-    const normalized = value.trim();
-    if (normalized) {
-      results.push(normalized);
+  try {
+    return await options.mutate();
+  } catch (error2) {
+    if (!isAmbiguousMutationFailure(error2)) {
+      throw error2;
     }
-    return;
-  }
-  if (typeof value === "number" || typeof value === "boolean") {
-    results.push(String(value));
-    return;
-  }
-  if (Array.isArray(value) || isIterable(value)) {
-    for (const entry of value) {
-      appendSecretValues(entry, results);
+    const adopted = await options.findExisting();
+    if (adopted !== null) {
+      return adopted;
     }
+    throw error2;
   }
 }
-function normalizeSecretValues(secretValues) {
-  const values = [];
-  appendSecretValues(secretValues, values);
-  return [...new Set(values)].sort((left, right) => right.length - left.length);
-}
-function redactSecrets(input, secretValues, replacement = REDACTED) {
-  const source = String(input ?? "");
-  const secrets = normalizeSecretValues(secretValues);
-  if (!source || secrets.length === 0) {
-    return source;
+var BifrostCatalogClient = class {
+  tokenProvider;
+  teamId;
+  apiKey;
+  fetchFn;
+  secretValues;
+  bifrostProxyUrl;
+  observabilityBaseUrl;
+  observabilityEnv;
+  constructor(options) {
+    this.tokenProvider = options.tokenProvider ?? new AccessTokenProvider({
+      accessToken: options.accessToken,
+      apiKey: options.apiKey
+    });
+    this.teamId = options.teamId;
+    this.apiKey = options.apiKey;
+    this.fetchFn = options.fetchFn ?? globalThis.fetch;
+    this.secretValues = [this.tokenProvider.current(), options.apiKey].filter(Boolean);
+    const base = (options.bifrostBaseUrl || DEFAULT_BIFROST_BASE_URL).replace(/\/+$/, "");
+    this.bifrostProxyUrl = `${base}${BIFROST_PROXY_PATH}`;
+    this.observabilityBaseUrl = (options.observabilityBaseUrl || DEFAULT_OBSERVABILITY_BASE_URL).replace(/\/+$/, "");
+    this.observabilityEnv = options.observabilityEnv || DEFAULT_OBSERVABILITY_ENV;
   }
-  return secrets.reduce((sanitized, secret) => {
-    if (!secret) {
-      return sanitized;
+  setApiKey(apiKey) {
+    this.apiKey = apiKey;
+    if (apiKey && !this.secretValues.includes(apiKey)) {
+      this.secretValues.push(apiKey);
     }
-    return sanitized.split(secret).join(replacement);
-  }, source);
-}
-function createSecretMasker(secretValues, replacement = REDACTED) {
-  return (input) => redactSecrets(input, secretValues, replacement);
-}
-function headerEntries(headers) {
-  if (headers instanceof Headers) {
-    return Array.from(headers.entries());
-  }
-  if (Array.isArray(headers)) {
-    return headers.map(([name, value]) => [name, String(value)]);
   }
-  return Object.entries(headers).map(([name, value]) => [name, String(value)]);
-}
-function sanitizeHeaders(headers, secretValues) {
-  if (!headers) {
-    return {};
-  }
-  const sanitized = {};
-  for (const [name, value] of headerEntries(headers)) {
-    const normalizedName = name.toLowerCase();
-    sanitized[normalizedName] = SENSITIVE_HEADER_NAMES.has(normalizedName) ? REDACTED : redactSecrets(value, secretValues);
-  }
-  return sanitized;
-}
-
-// src/lib/http-error.ts
-function truncate(value, limit) {
-  if (value.length <= limit) {
-    return value;
-  }
-  return `${value.slice(0, limit)}...[truncated]`;
-}
-function buildMessage(init) {
-  const method = String(init.method || "GET").toUpperCase();
-  const status = `${init.status}${init.statusText ? ` ${init.statusText}` : ""}`;
-  const url = redactSecrets(init.url, init.secretValues);
-  const body = truncate(
-    redactSecrets(init.responseBody || "", init.secretValues),
-    Math.max(0, init.bodyLimit ?? 800)
-  );
-  return body ? `${method} ${url} failed: ${status} - ${body}` : `${method} ${url} failed: ${status}`;
-}
-var HttpError = class _HttpError extends Error {
-  method;
-  requestHeaders;
-  responseBody;
-  secretValues;
-  status;
-  statusText;
-  url;
-  constructor(init) {
-    super(buildMessage(init));
-    this.name = "HttpError";
-    this.method = String(init.method || "GET").toUpperCase();
-    this.requestHeaders = init.requestHeaders;
-    this.responseBody = init.responseBody || "";
-    this.secretValues = init.secretValues;
-    this.status = init.status;
-    this.statusText = init.statusText;
-    this.url = init.url;
-  }
-  static async fromResponse(response, init) {
-    const responseBody = init.responseBody ?? await response.text().catch(() => "");
-    return new _HttpError({
-      ...init,
-      responseBody,
-      status: response.status,
-      statusText: response.statusText
-    });
-  }
-  toJSON() {
-    return {
-      method: this.method,
-      name: this.name,
-      requestHeaders: sanitizeHeaders(this.requestHeaders, this.secretValues),
-      responseBody: redactSecrets(this.responseBody, this.secretValues),
-      status: this.status,
-      statusText: this.statusText,
-      url: redactSecrets(this.url, this.secretValues)
-    };
-  }
-};
-
-// src/lib/bifrost-client.ts
-var DEFAULT_BIFROST_BASE_URL = POSTMAN_ENDPOINT_PROFILES.prod.bifrostBaseUrl;
-var BIFROST_PROXY_PATH = "/ws/proxy";
-var DEFAULT_OBSERVABILITY_BASE_URL = POSTMAN_ENDPOINT_PROFILES.prod.observabilityBaseUrl;
-var DEFAULT_OBSERVABILITY_ENV = POSTMAN_ENDPOINT_PROFILES.prod.observabilityEnv;
-var MAX_DISCOVERED_SERVICE_PAGES = 100;
-var MAX_PROVIDER_SERVICE_PAGES = 100;
-function isExpiredAuthError(status, body) {
-  return status === 401 || body.includes("UNAUTHENTICATED") || body.includes("authenticationError");
-}
-var BifrostCatalogClient = class {
-  tokenProvider;
-  teamId;
-  apiKey;
-  fetchFn;
-  secretValues;
-  bifrostProxyUrl;
-  observabilityBaseUrl;
-  observabilityEnv;
-  constructor(options) {
-    this.tokenProvider = options.tokenProvider ?? new AccessTokenProvider({
-      accessToken: options.accessToken,
-      apiKey: options.apiKey
-    });
-    this.teamId = options.teamId;
-    this.apiKey = options.apiKey;
-    this.fetchFn = options.fetchFn ?? globalThis.fetch;
-    this.secretValues = [this.tokenProvider.current(), options.apiKey].filter(Boolean);
-    const base = (options.bifrostBaseUrl || DEFAULT_BIFROST_BASE_URL).replace(/\/+$/, "");
-    this.bifrostProxyUrl = `${base}${BIFROST_PROXY_PATH}`;
-    this.observabilityBaseUrl = (options.observabilityBaseUrl || DEFAULT_OBSERVABILITY_BASE_URL).replace(/\/+$/, "");
-    this.observabilityEnv = options.observabilityEnv || DEFAULT_OBSERVABILITY_ENV;
-  }
-  setApiKey(apiKey) {
-    this.apiKey = apiKey;
-    if (apiKey && !this.secretValues.includes(apiKey)) {
-      this.secretValues.push(apiKey);
-    }
-  }
-  registerAccessToken(token) {
-    if (token && !this.secretValues.includes(token)) {
-      this.secretValues.push(token);
-    }
+  registerAccessToken(token) {
+    if (token && !this.secretValues.includes(token)) {
+      this.secretValues.push(token);
+    }
   }
   /**
    * Build Bifrost proxy headers.
-   * x-entity-team-id is ONLY included when teamId is present (org-mode tokens).
-   * Non-org-mode tokens must OMIT it so Bifrost resolves team from the access token.
+   * x-entity-team-id is ONLY included when teamId is present (explicit input /
+   * POSTMAN_TEAM_ID). Non-org-mode tokens must OMIT it so Bifrost resolves team
+   * from the access token. Team is never inferred from PMAK.
    */
   headers() {
     const h = {
@@ -21834,7 +21894,7 @@ var BifrostCatalogClient = class {
       mask: createSecretMasker(this.secretValues)
     };
   }
-  async proxyRequest(method, path7, body = {}, operation = "api-catalog request") {
+  async proxyRequest(method, path7, body = {}, operation = "api-catalog request", allowAuthReplay = false) {
     const send2 = async () => this.fetchFn(this.bifrostProxyUrl, {
       method: "POST",
       headers: this.headers(),
@@ -21848,7 +21908,7 @@ var BifrostCatalogClient = class {
     let response = await send2();
     if (!response.ok) {
       const bodyText = await response.text().catch(() => "");
-      if (isExpiredAuthError(response.status, bodyText) && this.tokenProvider.canRefresh()) {
+      if (allowAuthReplay && isExpiredAuthError(response.status, bodyText) && this.tokenProvider.canRefresh()) {
         try {
           const refreshed = await this.tokenProvider.refresh();
           this.registerAccessToken(refreshed);
@@ -21899,7 +21959,7 @@ var BifrostCatalogClient = class {
     }
     return data;
   }
-  async akitaProxyRequest(method, path7, body = {}, operation = "Insights request") {
+  async akitaProxyRequest(method, path7, body = {}, operation = "Insights request", allowAuthReplay = false) {
     const send2 = async () => this.fetchFn(this.bifrostProxyUrl, {
       method: "POST",
       headers: this.headers(),
@@ -21913,7 +21973,7 @@ var BifrostCatalogClient = class {
     let response = await send2();
     if (!response.ok) {
       const text = await response.text().catch(() => "");
-      if (isExpiredAuthError(response.status, text) && this.tokenProvider.canRefresh()) {
+      if (allowAuthReplay && isExpiredAuthError(response.status, text) && this.tokenProvider.canRefresh()) {
         try {
           const refreshed = await this.tokenProvider.refresh();
           this.registerAccessToken(refreshed);
@@ -21942,6 +22002,17 @@ ${advised.message}` : advised.message : text;
     const data = await response.json();
     return { ok: true, status: response.status, data, errorText: "" };
   }
+  throwAkitaFailure(status, errorText, operation, path7) {
+    const httpErr = new HttpError({
+      method: "POST",
+      url: `bifrost:akita:${path7}`,
+      status,
+      statusText: status >= 500 ? "Error" : "Client Error",
+      responseBody: errorText
+    });
+    const advised = adviseFromHttpError(httpErr, this.adviceContext(operation));
+    throw advised ?? httpErr;
+  }
   async listDiscoveredServices() {
     return retry(
       async () => {
@@ -21969,26 +22040,80 @@ ${advised.message}` : advised.message : text;
         }
         return allItems;
       },
-      { maxAttempts: 3, delayMs: 2e3, backoffMultiplier: 2 }
+      SAFE_READ_RETRY
     );
   }
-  async prepareCollection(serviceId, workspaceId) {
+  /** List discovered + integrated services for exact link reconciliation. */
+  async listServicesForReconcile() {
     return retry(
       async () => {
+        const allItems = [];
+        let cursor = null;
+        const seenCursors = /* @__PURE__ */ new Set();
+        for (let page = 0; page < MAX_DISCOVERED_SERVICE_PAGES; page += 1) {
+          const query = cursor ? `?cursor=${encodeURIComponent(cursor)}` : "";
+          const data = await this.proxyRequest(
+            "GET",
+            `/api/v1/onboarding/discovered-services${query}`,
+            {},
+            "service link reconciliation"
+          );
+          allItems.push(...data.items || []);
+          if (data.total && allItems.length >= data.total) {
+            break;
+          }
+          const nextCursor = data.nextCursor || null;
+          if (!nextCursor || seenCursors.has(nextCursor)) {
+            break;
+          }
+          seenCursors.add(nextCursor);
+          cursor = nextCursor;
+        }
+        return allItems;
+      },
+      SAFE_READ_RETRY
+    );
+  }
+  async findPreparedCollection(serviceId, workspaceId) {
+    const services = await this.listServicesForReconcile();
+    const match = services.find(
+      (service) => service.id === serviceId && Boolean(service.collectionId) && service.workspaceId === workspaceId
+    );
+    return match?.collectionId ? String(match.collectionId) : null;
+  }
+  async findGitLink(params) {
+    const services = await this.listServicesForReconcile();
+    const match = services.find((service) => {
+      if (service.id !== params.serviceId) return false;
+      if (service.workspaceId !== params.workspaceId) return false;
+      if (service.environmentId !== params.environmentId) return false;
+      if (!service.gitRepositoryUrl) return false;
+      return normalizeRepoUrl(service.gitRepositoryUrl) === normalizeRepoUrl(params.gitRepositoryUrl);
+    });
+    return match ? true : null;
+  }
+  async prepareCollection(serviceId, workspaceId) {
+    return mutateOnceThenReconcile({
+      findExisting: () => this.findPreparedCollection(serviceId, workspaceId),
+      mutate: async () => {
         const data = await this.proxyRequest(
           "POST",
           "/api/v1/onboarding/prepare-collection",
           { service_id: String(serviceId), workspace_id: workspaceId },
-          "collection preparation"
+          "collection preparation",
+          false
         );
+        if (!data?.id) {
+          throw new Error("prepare-collection succeeded without a collection id");
+        }
         return data.id;
-      },
-      { maxAttempts: 3, delayMs: 2e3, backoffMultiplier: 2 }
-    );
+      }
+    });
   }
   async onboardGit(params) {
-    await retry(
-      async () => {
+    await mutateOnceThenReconcile({
+      findExisting: () => this.findGitLink(params),
+      mutate: async () => {
         const body = {
           via_integrations: false,
           git_service_name: "github",
@@ -22004,24 +22129,32 @@ ${advised.message}` : advised.message : text;
           "POST",
           "/api/v1/onboarding/git",
           body,
-          "git onboarding"
+          "git onboarding",
+          false
         );
-      },
-      { maxAttempts: 2, delayMs: 3e3 }
-    );
+        return true;
+      }
+    });
   }
-  async resolveProviderServiceId(projectName, clusterName) {
+  async listProviderServices() {
     const allServices = [];
     let page = 1;
     const pageSize = 100;
     for (let pageCount = 0; pageCount < MAX_PROVIDER_SERVICE_PAGES; pageCount += 1) {
       const result = await this.akitaProxyRequest(
         "GET",
-        `/v2/api-catalog/services?status=discovered&populate_endpoints=false&populate_discovery_metadata=true&page=${page}&page_size=${pageSize}`,
+        `/v2/api-catalog/services?populate_endpoints=false&populate_discovery_metadata=true&page=${page}&page_size=${pageSize}`,
         {},
         "provider service resolution"
       );
-      if (!result.ok || !result.data) return null;
+      if (!result.ok || !result.data) {
+        this.throwAkitaFailure(
+          result.status,
+          result.errorText,
+          "provider service resolution",
+          "GET /v2/api-catalog/services"
+        );
+      }
       const services = result.data.services || [];
       allServices.push(...services);
       if (result.data.total && allServices.length >= result.data.total) {
@@ -22032,86 +22165,225 @@ ${advised.message}` : advised.message : text;
       }
       page++;
     }
+    return allServices;
+  }
+  async resolveProviderServiceId(projectName, clusterName) {
+    const allServices = await retry(
+      async () => this.listProviderServices(),
+      SAFE_READ_RETRY
+    );
     if (clusterName) {
       const fullName = `${clusterName}/${projectName}`;
       const exactMatch = allServices.find((s) => s.name === fullName);
       return exactMatch?.id || null;
     }
-    const finalSegmentMatch = allServices.find(
+    const finalSegmentMatches = allServices.filter(
       (s) => getFinalServiceSegment(s.name) === projectName
     );
-    if (finalSegmentMatch) return finalSegmentMatch.id;
-    const bracketedMatch = allServices.find(
+    if (finalSegmentMatches.length > 1) {
+      throw new Error(
+        `Ambiguous Insights provider service "${projectName}": multiple final-segment matches (${finalSegmentMatches.map((s) => s.name).join(", ")}). Provide cluster-name to select the canonical service identity.`
+      );
+    }
+    if (finalSegmentMatches.length === 1) return finalSegmentMatches[0].id;
+    const bracketedMatches = allServices.filter(
       (s) => getFinalServiceSegment(s.name).includes(`[${projectName}]`)
     );
-    return bracketedMatch?.id || null;
+    if (bracketedMatches.length > 1) {
+      throw new Error(
+        `Ambiguous Insights provider service "${projectName}": multiple bracketed matches. Provide cluster-name to select the canonical service identity.`
+      );
+    }
+    return bracketedMatches[0]?.id || null;
+  }
+  async findAcknowledgedOnboarding(providerServiceId, workspaceId, systemEnvironmentId) {
+    const services = await this.listProviderServices();
+    const match = services.find(
+      (service) => service.id === providerServiceId && service.workspace_id === workspaceId && service.system_env === systemEnvironmentId && (service.status === "onboarded" || service.status === "integrated" || Boolean(service.workspace_id))
+    );
+    return match ? true : null;
   }
   async acknowledgeOnboarding(providerServiceId, workspaceId, systemEnvironmentId) {
-    const result = await this.akitaProxyRequest(
-      "POST",
-      "/v2/api-catalog/services/onboard",
-      {
-        services: [{
-          service_id: providerServiceId,
-          workspace_id: workspaceId,
-          system_env: systemEnvironmentId
-        }]
+    await mutateOnceThenReconcile({
+      findExisting: () => this.findAcknowledgedOnboarding(providerServiceId, workspaceId, systemEnvironmentId),
+      mutate: async () => {
+        const result = await this.akitaProxyRequest(
+          "POST",
+          "/v2/api-catalog/services/onboard",
+          {
+            services: [{
+              service_id: providerServiceId,
+              workspace_id: workspaceId,
+              system_env: systemEnvironmentId
+            }]
+          },
+          "Insights onboarding acknowledgment",
+          false
+        );
+        if (!result.ok) {
+          this.throwAkitaFailure(
+            result.status,
+            result.errorText,
+            "Insights onboarding acknowledgment",
+            "POST /v2/api-catalog/services/onboard"
+          );
+        }
+        return true;
+      }
+    });
+  }
+  async findWorkspaceAcknowledged(workspaceId) {
+    const result = await retry(
+      async () => {
+        const response = await this.akitaProxyRequest(
+          "GET",
+          `/v2/workspaces/${workspaceId}/onboarding/acknowledge`,
+          {},
+          "workspace onboarding acknowledgment status"
+        );
+        if (!response.ok) {
+          this.throwAkitaFailure(
+            response.status,
+            response.errorText,
+            "workspace onboarding acknowledgment status",
+            `GET /v2/workspaces/${workspaceId}/onboarding/acknowledge`
+          );
+        }
+        return response;
       },
-      "Insights onboarding acknowledgment"
+      SAFE_READ_RETRY
     );
-    if (!result.ok) {
-      throw new Error(`Insights acknowledge failed: ${result.status} ${result.errorText}`);
-    }
+    return result.data?.onboarding_acknowledged ? true : null;
   }
   async acknowledgeWorkspace(workspaceId) {
-    const result = await this.akitaProxyRequest(
-      "POST",
-      `/v2/workspaces/${workspaceId}/onboarding/acknowledge`,
-      {},
-      "workspace onboarding acknowledgment"
-    );
-    if (!result.ok) {
-      throw new Error(`Workspace acknowledge failed: ${result.status} ${result.errorText}`);
-    }
+    await mutateOnceThenReconcile({
+      findExisting: () => this.findWorkspaceAcknowledged(workspaceId),
+      mutate: async () => {
+        const result = await this.akitaProxyRequest(
+          "POST",
+          `/v2/workspaces/${workspaceId}/onboarding/acknowledge`,
+          {},
+          "workspace onboarding acknowledgment",
+          false
+        );
+        if (!result.ok) {
+          this.throwAkitaFailure(
+            result.status,
+            result.errorText,
+            "workspace onboarding acknowledgment",
+            `POST /v2/workspaces/${workspaceId}/onboarding/acknowledge`
+          );
+        }
+        return true;
+      }
+    });
   }
-  // PMAK-only by proven exception. A live probe against the observability
-  // application-binding endpoint (POST /v2/agent/api-catalog/workspaces/:id/
-  // applications) showed x-access-token is rejected identically to the x-api-key
-  // control: both return 401 {"message":"Postman User not found"} for a
-  // service-account credential, because the observability service has no
-  // "Postman User" for a service account. The access token offers no improvement
-  // over the API key here, so this route is not migrated to access-token-primary
-  // (the suite-wide migration explicitly leaves probe-failed routes on PMAK).
-  async createApplication(workspaceId, systemEnv) {
+  async findApplication(workspaceId, systemEnv, expectedServiceId) {
     const response = await this.fetchFn(
       `${this.observabilityBaseUrl}/v2/agent/api-catalog/workspaces/${workspaceId}/applications`,
       {
-        method: "POST",
+        method: "GET",
         headers: {
           "x-api-key": this.apiKey,
           "x-postman-env": this.observabilityEnv,
           "Content-Type": "application/json"
-        },
-        body: JSON.stringify({ system_env: systemEnv })
+        }
       }
     );
     if (!response.ok) {
       const httpErr = await HttpError.fromResponse(response, {
-        method: "POST",
-        url: `observability:createApplication(${workspaceId})`,
+        method: "GET",
+        url: `observability:listApplications(${workspaceId})`,
         secretValues: this.secretValues
       });
-      const advised = adviseFromHttpError(httpErr, this.adviceContext("application binding"));
+      const advised = adviseFromHttpError(httpErr, this.adviceContext("application binding lookup"));
       throw advised ?? httpErr;
     }
-    return response.json();
+    const data = await response.json();
+    const matches = (data.applications || []).filter(
+      (app) => app.application_id && app.service_id && app.system_env === systemEnv && (!expectedServiceId || app.service_id === expectedServiceId)
+    );
+    if (matches.length > 1) {
+      throw new Error(
+        `Multiple application bindings match workspace ${workspaceId}, system environment ${systemEnv}, and service ${expectedServiceId || "(unspecified)"}`
+      );
+    }
+    const match = matches[0];
+    if (!match?.application_id || !match.service_id) {
+      return null;
+    }
+    return {
+      application_id: String(match.application_id),
+      service_id: String(match.service_id)
+    };
+  }
+  // PMAK-only by proven exception. A live probe against the observability
+  // application-binding endpoint (POST /v2/agent/api-catalog/workspaces/:id/
+  // applications) showed x-access-token is rejected identically to the x-api-key
+  // control: both return 401 {"message":"Postman User not found"} for a
+  // service-account credential, because the observability service has no
+  // "Postman User" for a service account. The access token offers no improvement
+  // over the API key here, so this route is not migrated to access-token-primary
+  // (the suite-wide migration explicitly leaves probe-failed routes on PMAK).
+  async createApplication(workspaceId, systemEnv, expectedServiceId) {
+    return mutateOnceThenReconcile({
+      findExisting: () => retry(
+        () => this.findApplication(workspaceId, systemEnv, expectedServiceId),
+        SAFE_READ_RETRY
+      ),
+      mutate: async () => {
+        const response = await this.fetchFn(
+          `${this.observabilityBaseUrl}/v2/agent/api-catalog/workspaces/${workspaceId}/applications`,
+          {
+            method: "POST",
+            headers: {
+              "x-api-key": this.apiKey,
+              "x-postman-env": this.observabilityEnv,
+              "Content-Type": "application/json"
+            },
+            body: JSON.stringify({ system_env: systemEnv })
+          }
+        );
+        if (!response.ok) {
+          const httpErr = await HttpError.fromResponse(response, {
+            method: "POST",
+            url: `observability:createApplication(${workspaceId})`,
+            secretValues: this.secretValues
+          });
+          const advised = adviseFromHttpError(httpErr, this.adviceContext("application binding"));
+          throw advised ?? httpErr;
+        }
+        const created = await response.json();
+        if (expectedServiceId && created.service_id !== expectedServiceId) {
+          throw new Error(
+            `Application binding credential/scope mismatch: expected service ${expectedServiceId}, received ${created.service_id}`
+          );
+        }
+        return created;
+      }
+    });
   }
   async getTeamVerificationToken(workspaceId) {
-    const result = await this.akitaProxyRequest(
-      "GET",
-      `/v2/workspaces/${workspaceId}/team-verification-token`,
-      {},
-      "team verification token retrieval"
+    const result = await retry(
+      async () => {
+        const page = await this.akitaProxyRequest(
+          "GET",
+          `/v2/workspaces/${workspaceId}/team-verification-token`,
+          {},
+          "team verification token retrieval"
+        );
+        if (!page.ok && (page.status === 408 || page.status === 429 || page.status >= 500)) {
+          throw new HttpError({
+            method: "GET",
+            url: `bifrost:akita:GET /v2/workspaces/${workspaceId}/team-verification-token`,
+            status: page.status,
+            statusText: "Error",
+            responseBody: page.errorText
+          });
+        }
+        return page;
+      },
+      SAFE_READ_RETRY
     );
     if (!result.ok || !result.data) return null;
     return result.data.team_verification_token || null;
@@ -22144,24 +22416,87 @@ ${advised.message}` : advised.message : text;
     return String(apikey.key);
   }
 };
+function buildCanonicalServiceIdentity(service, projectName, clusterName, providerServiceId) {
+  const derivedCluster = clusterName || (service.name.includes("/") ? service.name.slice(0, service.name.lastIndexOf("/")) : null);
+  return {
+    serviceId: service.id,
+    serviceName: service.name,
+    clusterName: derivedCluster,
+    projectName,
+    ...providerServiceId ? { providerServiceId } : {}
+  };
+}
 function findDiscoveredService(services, projectName, clusterName) {
   if (clusterName) {
     const fullName = `${clusterName}/${projectName}`;
-    return services.find((s) => s.name === fullName);
+    const match = services.find((s) => s.name === fullName);
+    if (match) {
+      match.canonicalIdentity = buildCanonicalServiceIdentity(match, projectName, clusterName);
+    }
+    return match;
   }
-  const finalSegmentMatch = services.find(
+  const finalSegmentMatches = services.filter(
     (service) => getFinalServiceSegment(service.name) === projectName
   );
-  if (finalSegmentMatch) return finalSegmentMatch;
-  return services.find(
+  if (finalSegmentMatches.length > 1) {
+    throw new Error(
+      `Ambiguous discovered service "${projectName}": multiple final-segment matches (${finalSegmentMatches.map((s) => s.name).join(", ")}). cluster-name is required to select the canonical service identity.`
+    );
+  }
+  if (finalSegmentMatches.length === 1) {
+    const match = finalSegmentMatches[0];
+    match.canonicalIdentity = buildCanonicalServiceIdentity(match, projectName);
+    return match;
+  }
+  const bracketedMatches = services.filter(
     (service) => getFinalServiceSegment(service.name).includes(`[${projectName}]`)
   );
+  if (bracketedMatches.length > 1) {
+    throw new Error(
+      `Ambiguous discovered service "${projectName}": multiple bracketed matches. cluster-name is required to select the canonical service identity.`
+    );
+  }
+  if (bracketedMatches.length === 1) {
+    const match = bracketedMatches[0];
+    match.canonicalIdentity = buildCanonicalServiceIdentity(match, projectName);
+    return match;
+  }
+  return void 0;
 }
 function getFinalServiceSegment(serviceName) {
   const lastSlash = serviceName.lastIndexOf("/");
   return lastSlash === -1 ? serviceName : serviceName.slice(lastSlash + 1);
 }
 
+// src/lib/input.ts
+function normalizeInputValue(value) {
+  return String(value ?? "").trim();
+}
+function runnerInputEnvName(name) {
+  return `INPUT_${name.replace(/ /g, "_").toUpperCase()}`;
+}
+function normalizedInputEnvName(name) {
+  return `INPUT_${name.replace(/-/g, "_").toUpperCase()}`;
+}
+function getInput2(name, env = process.env) {
+  const normalizedName = normalizedInputEnvName(name);
+  const runnerName = runnerInputEnvName(name);
+  const normalizedRaw = env[normalizedName];
+  const runnerRaw = runnerName === normalizedName ? void 0 : env[runnerName];
+  const hasNormalized = normalizedRaw !== void 0;
+  const hasRunner = runnerRaw !== void 0;
+  if (hasNormalized && hasRunner) {
+    const normalizedValue = normalizeInputValue(normalizedRaw);
+    const runnerValue = normalizeInputValue(runnerRaw);
+    if (normalizedValue !== runnerValue) {
+      throw new Error(
+        `Conflicting values for ${name}: ${normalizedName}=${JSON.stringify(normalizedValue)} vs ${runnerName}=${JSON.stringify(runnerValue)}`
+      );
+    }
+  }
+  return normalizeInputValue(hasNormalized ? normalizedRaw : runnerRaw);
+}
+
 // node_modules/@postman-cse/automation-telemetry-core/dist/ci-context.js
 function norm(value) {
   const trimmed = (value ?? "").trim();
@@ -22318,7 +22653,7 @@ function normalize(value) {
   const trimmed = (value ?? "").trim();
   return trimmed.length > 0 ? trimmed : void 0;
 }
-function normalizeRepoUrl(url) {
+function normalizeRepoUrl2(url) {
   const raw = normalize(url);
   if (!raw) {
     return void 0;
@@ -22386,7 +22721,7 @@ function classifyRefKind(env = process.env) {
   return "unknown";
 }
 function detectRepoContext(input, env = process.env) {
-  const repoUrl = normalizeRepoUrl(input.repoUrl) ?? normalizeRepoUrl(env.GITHUB_SERVER_URL && env.GITHUB_REPOSITORY ? `${env.GITHUB_SERVER_URL}/${env.GITHUB_REPOSITORY}` : void 0) ?? normalizeRepoUrl(env.CI_PROJECT_URL) ?? normalizeRepoUrl(env.BITBUCKET_GIT_HTTP_ORIGIN) ?? normalizeRepoUrl(env.BUILD_REPOSITORY_URI);
+  const repoUrl = normalizeRepoUrl2(input.repoUrl) ?? normalizeRepoUrl2(env.GITHUB_SERVER_URL && env.GITHUB_REPOSITORY ? `${env.GITHUB_SERVER_URL}/${env.GITHUB_REPOSITORY}` : void 0) ?? normalizeRepoUrl2(env.CI_PROJECT_URL) ?? normalizeRepoUrl2(env.BITBUCKET_GIT_HTTP_ORIGIN) ?? normalizeRepoUrl2(env.BUILD_REPOSITORY_URI);
   const repoSlug = normalize(input.repoSlug) ?? normalize(env.GITHUB_REPOSITORY) ?? normalize(env.CI_PROJECT_PATH) ?? (env.BITBUCKET_WORKSPACE && env.BITBUCKET_REPO_SLUG ? normalize(`${env.BITBUCKET_WORKSPACE}/${env.BITBUCKET_REPO_SLUG}`) : void 0) ?? normalize(env.BUILD_REPOSITORY_NAME);
   const ref = normalize(input.ref) ?? normalize(env.GITHUB_REF_NAME) ?? normalize(env.CI_COMMIT_REF_NAME) ?? normalize(env.BITBUCKET_BRANCH) ?? normalize(env.BUILD_SOURCEBRANCHNAME);
   const sha = normalize(input.sha) ?? normalize(env.GITHUB_SHA) ?? normalize(env.CI_COMMIT_SHA) ?? normalize(env.BITBUCKET_COMMIT) ?? normalize(env.BUILD_SOURCEVERSION);
@@ -22563,7 +22898,7 @@ var DEFAULT_POSTMAN_BIFROST_BASE = PROD_ENDPOINTS.bifrostBaseUrl;
 var DEFAULT_POSTMAN_IAPUB_BASE = PROD_ENDPOINTS.iapubBaseUrl;
 var DEFAULT_POSTMAN_OBSERVABILITY_BASE = PROD_ENDPOINTS.observabilityBaseUrl;
 function parsePreflightMode(value) {
-  const normalized = String(value || "warn").trim().toLowerCase();
+  const normalized = String(value || "enforce").trim().toLowerCase();
   if (normalized === "enforce" || normalized === "warn") {
     return normalized;
   }
@@ -22571,6 +22906,27 @@ function parsePreflightMode(value) {
     `Unsupported credential-preflight "${value}". Supported values: enforce, warn`
   );
 }
+function parseServiceNotFoundPolicy(value) {
+  const normalized = String(value || "fail").trim().toLowerCase();
+  if (normalized === "fail" || normalized === "warn") {
+    return normalized;
+  }
+  throw new Error(
+    `Unsupported service-not-found-policy "${value}". Supported values: fail, warn`
+  );
+}
+function parseCreateApiKey(value) {
+  const normalized = String(value || "false").trim().toLowerCase();
+  if (normalized === "true") {
+    return true;
+  }
+  if (normalized === "false" || normalized === "") {
+    return false;
+  }
+  throw new Error(
+    `Unsupported create-api-key "${value}". Supported values: true, false`
+  );
+}
 function trimTrailingSlash(value) {
   return value.replace(/\/+$/, "");
 }
@@ -22589,29 +22945,12 @@ async function validateApiKey(apiKey, apiBase = DEFAULT_POSTMAN_API_BASE) {
   const teamId = data?.user?.teamId ? String(data.user.teamId) : void 0;
   return { valid: true, teamId };
 }
-async function getTeams(apiKey, apiBase = DEFAULT_POSTMAN_API_BASE) {
-  try {
-    const res = await fetch(`${trimTrailingSlash(apiBase)}/teams`, {
-      method: "GET",
-      headers: { "x-api-key": apiKey }
-    });
-    if (!res.ok) return [];
-    const data = await res.json();
-    return (data?.data ?? []).filter((t) => t?.id && t?.name).map((t) => ({
-      id: Number(t.id),
-      name: String(t.name),
-      ...t.organizationId != null ? { organizationId: Number(t.organizationId) } : {}
-    }));
-  } catch {
-    return [];
-  }
-}
 function clamp(value, min, max, fallback) {
   const parsed = Number.isFinite(value) ? value : fallback;
   return Math.min(max, Math.max(min, parsed));
 }
 function resolveInputs(env = process.env) {
-  const get = (name, fallback = "") => env[`INPUT_${name.toUpperCase().replace(/-/g, "_")}`]?.trim() || fallback;
+  const get = (name, fallback = "") => getInput2(name, env) || fallback;
   const projectName = get("project-name");
   if (!projectName) throw new Error("project-name is required");
   const postmanAccessToken = get("postman-access-token");
@@ -22652,7 +22991,9 @@ function resolveInputs(env = process.env) {
     postmanApiKey,
     postmanTeamId,
     githubToken: get("github-token", env.GITHUB_TOKEN || ""),
-    credentialPreflight: parsePreflightMode(get("credential-preflight", "warn")),
+    credentialPreflight: parsePreflightMode(get("credential-preflight", "enforce")),
+    createApiKey: parseCreateApiKey(get("create-api-key", "false")),
+    serviceNotFoundPolicy: parseServiceNotFoundPolicy(get("service-not-found-policy", "fail")),
     pollTimeoutSeconds: clamp(rawTimeout, POLL_TIMEOUT_MIN, POLL_TIMEOUT_MAX, POLL_TIMEOUT_DEFAULT),
     pollIntervalSeconds: clamp(rawInterval, POLL_INTERVAL_MIN, POLL_INTERVAL_MAX, POLL_INTERVAL_DEFAULT),
     postmanRegion,
@@ -22668,6 +23009,7 @@ async function runOnboarding(inputs, client, sleepFn = sleep, reporter = core_ex
   const timeoutMs = inputs.pollTimeoutSeconds * 1e3;
   const intervalMs = inputs.pollIntervalSeconds * 1e3;
   const startTime = Date.now();
+  const policy = inputs.serviceNotFoundPolicy ?? "fail";
   reporter.info(`Looking for discovered service matching "${inputs.clusterName ? `${inputs.clusterName}/` : ""}${inputs.projectName}"...`);
   let match = void 0;
   while (Date.now() - startTime < timeoutMs) {
@@ -22682,15 +23024,35 @@ async function runOnboarding(inputs, client, sleepFn = sleep, reporter = core_ex
     await sleepFn(intervalMs);
   }
   if (!match) {
-    reporter.warning(`Service "${inputs.projectName}" not found in discovered services after ${inputs.pollTimeoutSeconds}s`);
-    return {
-      discoveredServiceId: 0,
-      discoveredServiceName: "",
-      collectionId: "",
-      applicationId: "",
-      verificationToken: null,
-      status: "not-found"
-    };
+    const message = `Service "${inputs.projectName}" not found in discovered services after ${inputs.pollTimeoutSeconds}s`;
+    if (policy === "warn") {
+      reporter.warning(message);
+      return {
+        discoveredServiceId: 0,
+        discoveredServiceName: "",
+        collectionId: "",
+        applicationId: "",
+        verificationToken: null,
+        status: "not-found"
+      };
+    }
+    throw new Error(`${message}. Full linking requires a discovered service (service-not-found-policy=fail).`);
+  }
+  const canonicalBase = match.canonicalIdentity ?? buildCanonicalServiceIdentity(match, inputs.projectName, inputs.clusterName || void 0);
+  const providerServiceId = await client.resolveProviderServiceId(
+    inputs.projectName,
+    inputs.clusterName || void 0
+  );
+  if (!providerServiceId) {
+    throw new Error(
+      `Insights provider service "${canonicalBase.serviceName}" was not found. Full linking requires one exact canonical service identity.`
+    );
+  }
+  const sysEnvId = inputs.systemEnvironmentId || match.systemEnvironmentId || "";
+  if (!sysEnvId) {
+    throw new Error(
+      `No system environment id is available for "${canonicalBase.serviceName}"; refusing partial linking writes.`
+    );
   }
   reporter.info(`Preparing collection for service ${match.id} in workspace ${inputs.workspaceId}...`);
   const collectionId = await client.prepareCollection(match.id, inputs.workspaceId);
@@ -22710,27 +23072,12 @@ async function runOnboarding(inputs, client, sleepFn = sleep, reporter = core_ex
   } else {
     reporter.info(`Skipping git onboarding for non-GitHub repo: ${repoUrl}`);
   }
-  const providerServiceId = await client.resolveProviderServiceId(
-    inputs.projectName,
-    inputs.clusterName || void 0
-  );
-  let applicationId = "";
-  if (providerServiceId) {
-    const sysEnvId = inputs.systemEnvironmentId || match.systemEnvironmentId || "";
-    if (sysEnvId) {
-      reporter.info(`Acknowledging Insights onboarding for ${providerServiceId}...`);
-      await client.acknowledgeOnboarding(providerServiceId, inputs.workspaceId, sysEnvId);
-      reporter.info(`Insights acknowledged: ${providerServiceId}`);
-      reporter.info(`Creating application binding for workspace ${inputs.workspaceId} with system_env ${sysEnvId}...`);
-      const appResult = await client.createApplication(inputs.workspaceId, sysEnvId);
-      applicationId = appResult.application_id;
-      reporter.info(`Application binding created: ${appResult.application_id} for service ${appResult.service_id}`);
-    } else {
-      reporter.warning("No systemEnvironmentId available; skipping Insights acknowledgment and application binding");
-    }
-  } else {
-    reporter.warning("Could not resolve Akita provider service ID; skipping acknowledgment and application binding");
-  }
+  reporter.info(`Acknowledging Insights onboarding for ${providerServiceId}...`);
+  await client.acknowledgeOnboarding(providerServiceId, inputs.workspaceId, sysEnvId);
+  reporter.info(`Insights acknowledged: ${providerServiceId}`);
+  reporter.info(`Creating application binding for workspace ${inputs.workspaceId} with system_env ${sysEnvId}...`);
+  const appResult = await client.createApplication(inputs.workspaceId, sysEnvId, providerServiceId);
+  reporter.info(`Application binding created: ${appResult.application_id} for service ${appResult.service_id}`);
   reporter.info(`Acknowledging workspace onboarding for ${inputs.workspaceId}...`);
   await client.acknowledgeWorkspace(inputs.workspaceId);
   reporter.info("Workspace onboarding acknowledged");
@@ -22746,9 +23093,13 @@ async function runOnboarding(inputs, client, sleepFn = sleep, reporter = core_ex
     discoveredServiceId: match.id,
     discoveredServiceName: match.name,
     collectionId,
-    applicationId,
+    applicationId: appResult.application_id,
     verificationToken,
-    status: "success"
+    status: "success",
+    canonicalIdentity: {
+      ...canonicalBase,
+      ...providerServiceId ? { providerServiceId } : {}
+    }
   };
 }
 async function resolveApiKeyAndTeamId(inputs, client, reporter = core_exports) {
@@ -22757,6 +23108,7 @@ async function resolveApiKeyAndTeamId(inputs, client, reporter = core_exports) {
   let keyValid = false;
   let pmakIdentity;
   const apiBase = inputs.postmanApiBase || DEFAULT_POSTMAN_API_BASE;
+  const createApiKey = inputs.createApiKey === true;
   if (apiKey) {
     const result = await validateApiKey(apiKey, apiBase);
     keyValid = result.valid;
@@ -22767,49 +23119,36 @@ async function resolveApiKeyAndTeamId(inputs, client, reporter = core_exports) {
     }
   }
   if (!keyValid) {
-    reporter.info("Generating a new Postman API key via Bifrost identity service...");
-    const keyName = `insights-onboarding-action-${Date.now()}`;
+    if (!createApiKey) {
+      if (apiKey) {
+        throw new Error(
+          "postman-api-key is invalid or expired. Provide a valid key, or set create-api-key=true to opt in to durable Bifrost API-key creation."
+        );
+      }
+      throw new Error(
+        "postman-api-key is required for application binding. Provide a valid key, or set create-api-key=true to opt in to durable Bifrost API-key creation."
+      );
+    }
+    reporter.info("create-api-key=true: generating a durable Postman API key via Bifrost identity service...");
+    const keyName = `insights-onboarding-${inputs.projectName}`;
     apiKey = await client.createApiKey(keyName);
     reporter.setSecret(apiKey);
     client.setApiKey(apiKey);
-    reporter.info("New API key created successfully.");
-  }
-  let resolvedTeamId = teamId;
-  if (!resolvedTeamId && apiKey) {
-    try {
-      const teams = await getTeams(apiKey, apiBase);
-      if (teams.length > 1 && teams.every((t) => t.organizationId == null)) {
-        reporter.warning(
-          "GET /teams returned multiple teams but none include organizationId. Org-mode auto-detection may be degraded due to an upstream API change. Set postman-team-id explicitly if Bifrost calls fail."
-        );
-      }
-      const isOrgMode = teams.some((t) => t.organizationId != null);
-      if (isOrgMode) {
-        if (teams.length === 1) {
-          resolvedTeamId = String(teams[0].id);
-          reporter.info(
-            `Org-mode account detected. Using sub-team ${teams[0].id} (${teams[0].name ?? "unknown"}) for Bifrost calls.`
-          );
-        } else {
-          const meResult = await validateApiKey(apiKey, apiBase);
-          const meTeamId = meResult.teamId ? parseInt(meResult.teamId, 10) : NaN;
-          if (!Number.isNaN(meTeamId) && teams.some((t) => t.id === meTeamId)) {
-            resolvedTeamId = String(meTeamId);
-            reporter.info(
-              `Org-mode account detected. Using sub-team ${meTeamId} (from /me) for Bifrost calls.`
-            );
-          }
-        }
-      }
-    } catch {
+    const createdIdentity = await validateApiKey(apiKey, apiBase);
+    if (!createdIdentity.valid) {
+      throw new Error("The explicitly created postman-api-key could not be validated; refusing linking writes.");
     }
+    pmakIdentity = { source: "pmak/me", teamId: createdIdentity.teamId };
+    reporter.info(`New API key created successfully (${keyName}).`);
   }
-  if (resolvedTeamId) {
-    reporter.info(`Using postman-team-id for Bifrost headers: ${resolvedTeamId}`);
+  if (teamId) {
+    reporter.info(`Using explicit postman-team-id for Bifrost headers: ${teamId}`);
   } else {
-    reporter.info("No postman-team-id resolved; omitting x-entity-team-id so Bifrost resolves team from the access token.");
+    reporter.info(
+      "No postman-team-id / POSTMAN_TEAM_ID provided; omitting x-entity-team-id so Bifrost resolves team from the access token."
+    );
   }
-  return { apiKey, teamId: resolvedTeamId, pmakIdentity };
+  return { apiKey, teamId, pmakIdentity };
 }
 async function runCredentialPreflightForInputs(inputs, pmak, reporter, fetchImpl, liveAccessToken) {
   const accessToken = liveAccessToken ?? inputs.postmanAccessToken;
@@ -22846,6 +23185,26 @@ function createInsightsBifrostClient(inputs, tokenProvider, teamId, apiKey) {
 }
 
 // src/cli.ts
+var INPUT_NAMES = [
+  "project-name",
+  "workspace-id",
+  "environment-id",
+  "system-environment-id",
+  "cluster-name",
+  "repo-url",
+  "postman-access-token",
+  "postman-api-key",
+  "create-api-key",
+  "credential-preflight",
+  "service-not-found-policy",
+  "postman-team-id",
+  "github-token",
+  "poll-timeout-seconds",
+  "poll-interval-seconds",
+  "postman-region",
+  "postman-stack"
+];
+var OUTPUT_OPTION_NAMES = ["result-json", "dotenv-path"];
 var ConsoleReporter = class {
   secretValues = [];
   info(message) {
@@ -22867,51 +23226,101 @@ var ConsoleReporter = class {
     return masked;
   }
 };
-function readFlag(argv, name) {
-  const prefix = `--${name}=`;
-  for (let index = 0; index < argv.length; index += 1) {
-    const arg = argv[index];
-    if (arg === `--${name}`) {
-      return argv[index + 1];
-    }
-    if (arg?.startsWith(prefix)) {
-      return arg.slice(prefix.length);
+function normalizeCliFlag(name) {
+  return normalizedInputEnvName(name);
+}
+function resolvePackageVersion() {
+  const candidates = [];
+  if (typeof __filename === "string") {
+    candidates.push(import_node_path2.default.join(import_node_path2.default.dirname(__filename), "..", "package.json"));
+  }
+  candidates.push(import_node_path2.default.join(process.cwd(), "package.json"));
+  for (const candidate of candidates) {
+    try {
+      const packageJson = JSON.parse((0, import_node_fs2.readFileSync)(candidate, "utf8"));
+      if (packageJson.name === "@postman-cse/onboarding-insights" && packageJson.version) {
+        return String(packageJson.version).trim();
+      }
+    } catch {
     }
   }
-  return void 0;
+  return resolveActionVersion2();
 }
-function normalizeCliFlag(name) {
-  return `INPUT_${name.replace(/-/g, "_").toUpperCase()}`;
+function renderHelp() {
+  const inputFlags = INPUT_NAMES.map((name) => `  --${name} <value>`).join("\n");
+  return [
+    "Usage: postman-insights-onboard [options]",
+    "",
+    "Options:",
+    inputFlags,
+    "  --result-json <path>   Optional JSON output file (opt-in)",
+    "  --dotenv-path <path>   Optional dotenv output file",
+    "  --help                 Show this help and exit",
+    "  --version              Print version and exit",
+    ""
+  ].join("\n");
 }
 function parseCliArgs(argv, env = process.env) {
-  const inputNames = [
-    "project-name",
-    "workspace-id",
-    "environment-id",
-    "system-environment-id",
-    "cluster-name",
-    "repo-url",
-    "postman-access-token",
-    "postman-api-key",
-    "credential-preflight",
-    "postman-team-id",
-    "github-token",
-    "poll-timeout-seconds",
-    "poll-interval-seconds",
-    "postman-region",
-    "postman-stack"
-  ];
+  if (argv.includes("--help") || argv.includes("-h")) {
+    return { kind: "help" };
+  }
+  if (argv.includes("--version") || argv.includes("-V")) {
+    return { kind: "version" };
+  }
+  const allowed = /* @__PURE__ */ new Set([...INPUT_NAMES, ...OUTPUT_OPTION_NAMES]);
+  const seen = /* @__PURE__ */ new Set();
   const inputEnv = { ...env };
-  for (const name of inputNames) {
-    const value = readFlag(argv, name);
-    if (value !== void 0) {
-      inputEnv[normalizeCliFlag(name)] = value;
+  let resultJsonPath;
+  let dotenvPath;
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index];
+    if (!arg) {
+      continue;
+    }
+    if (!arg.startsWith("--")) {
+      throw new Error(`Unexpected positional argument: ${arg}`);
+    }
+    const equalsIndex = arg.indexOf("=");
+    const name = equalsIndex >= 0 ? arg.slice(2, equalsIndex) : arg.slice(2);
+    if (!allowed.has(name)) {
+      throw new Error(`Unknown option: --${name}`);
     }
+    if (seen.has(name)) {
+      throw new Error(`Duplicate option: --${name}`);
+    }
+    let value;
+    if (equalsIndex >= 0) {
+      value = arg.slice(equalsIndex + 1);
+    } else {
+      const next = argv[index + 1];
+      if (next === void 0 || next.startsWith("--")) {
+        throw new Error(`Missing value for --${name}`);
+      }
+      value = next;
+      index += 1;
+    }
+    if (value.length === 0) {
+      throw new Error(`Missing value for --${name}`);
+    }
+    seen.add(name);
+    if (name === "result-json") {
+      resultJsonPath = value;
+      continue;
+    }
+    if (name === "dotenv-path") {
+      dotenvPath = value;
+      continue;
+    }
+    const normalizedName = normalizedInputEnvName(name);
+    delete inputEnv[runnerInputEnvName(name)];
+    delete inputEnv[normalizedName];
+    inputEnv[normalizedName] = value;
   }
   return {
+    kind: "run",
     inputEnv,
-    resultJsonPath: readFlag(argv, "result-json") ?? "postman-insights-onboarding-result.json",
-    dotenvPath: readFlag(argv, "dotenv-path")
+    resultJsonPath,
+    dotenvPath
   };
 }
 function toDotenv(outputs) {
@@ -22920,18 +23329,63 @@ function toDotenv(outputs) {
     value
   ]).map(([key, value]) => `${key}=${JSON.stringify(value)}`).join("\n");
 }
-async function writeOptionalFile(filePath, content) {
+function assertWithinWorkspace(workspaceRoot, resolved, filePath) {
+  const relative2 = import_node_path2.default.relative(workspaceRoot, resolved);
+  if (relative2 === ".." || relative2.startsWith(`..${import_node_path2.default.sep}`) || import_node_path2.default.isAbsolute(relative2)) {
+    throw new Error(`Output path must stay within workspace: ${filePath}`);
+  }
+}
+async function findExistingAncestor(candidate) {
+  let current = candidate;
+  while (true) {
+    try {
+      return await (0, import_promises.realpath)(current);
+    } catch (error2) {
+      if (error2.code !== "ENOENT") {
+        throw error2;
+      }
+      const parent = import_node_path2.default.dirname(current);
+      if (parent === current) {
+        throw error2;
+      }
+      current = parent;
+    }
+  }
+}
+async function validateOutputPath(filePath) {
   if (!filePath) {
     return;
   }
-  const workspaceRoot = import_node_path2.default.resolve(process.cwd());
+  const workspaceRoot = await (0, import_promises.realpath)(process.cwd());
   const resolved = import_node_path2.default.resolve(workspaceRoot, filePath);
-  const relative2 = import_node_path2.default.relative(workspaceRoot, resolved);
-  if (relative2.startsWith("..") || import_node_path2.default.isAbsolute(relative2)) {
-    throw new Error(`Output path must stay within workspace: ${filePath}`);
-  }
+  assertWithinWorkspace(workspaceRoot, resolved, filePath);
+  const existingParent = await findExistingAncestor(import_node_path2.default.dirname(resolved));
+  assertWithinWorkspace(workspaceRoot, existingParent, filePath);
+}
+async function writeAtomicFile(filePath, content) {
+  const workspaceRoot = await (0, import_promises.realpath)(process.cwd());
+  const resolved = import_node_path2.default.resolve(workspaceRoot, filePath);
+  assertWithinWorkspace(workspaceRoot, resolved, filePath);
   await (0, import_promises.mkdir)(import_node_path2.default.dirname(resolved), { recursive: true });
-  await (0, import_promises.writeFile)(resolved, content, "utf8");
+  const resolvedParent = await (0, import_promises.realpath)(import_node_path2.default.dirname(resolved));
+  assertWithinWorkspace(workspaceRoot, resolvedParent, filePath);
+  const safeTarget = import_node_path2.default.join(resolvedParent, import_node_path2.default.basename(resolved));
+  const tempPath = import_node_path2.default.join(
+    resolvedParent,
+    `.${import_node_path2.default.basename(resolved)}.${process.pid}.${(0, import_node_crypto2.randomUUID)()}.tmp`
+  );
+  try {
+    await (0, import_promises.writeFile)(tempPath, content, { encoding: "utf8", flag: "wx", mode: 384 });
+    await (0, import_promises.rename)(tempPath, safeTarget);
+  } finally {
+    await (0, import_promises.rm)(tempPath, { force: true });
+  }
+}
+async function writeOptionalFile(filePath, content) {
+  if (!filePath) {
+    return;
+  }
+  await writeAtomicFile(filePath, content);
 }
 function toOutputs(result) {
   return {
@@ -22945,7 +23399,20 @@ function toOutputs(result) {
 }
 async function runCli(argv = process.argv.slice(2), runtime = {}) {
   const env = runtime.env ?? process.env;
-  const config = parseCliArgs(argv, env);
+  const writeStdout = runtime.writeStdout ?? ((chunk) => process.stdout.write(chunk));
+  const parsed = parseCliArgs(argv, env);
+  if (parsed.kind === "help") {
+    writeStdout(renderHelp());
+    return;
+  }
+  if (parsed.kind === "version") {
+    writeStdout(`${resolvePackageVersion()}
+`);
+    return;
+  }
+  const config = parsed;
+  await validateOutputPath(config.resultJsonPath);
+  await validateOutputPath(config.dotenvPath);
   const inputs = resolveInputs(config.inputEnv);
   const reporter = new ConsoleReporter();
   const mintHolder = {
@@ -22969,31 +23436,53 @@ async function runCli(argv = process.argv.slice(2), runtime = {}) {
     inputs.postmanTeamId,
     inputs.postmanApiKey
   );
-  const { apiKey, teamId, pmakIdentity } = await resolveApiKeyAndTeamId(
-    inputs,
-    preliminaryClient,
-    reporter
-  );
-  const activeTokenProvider = apiKey !== inputs.postmanApiKey ? new AccessTokenProvider({
-    accessToken: tokenProvider.current(),
-    apiKey,
-    apiBaseUrl: inputs.postmanApiBase || DEFAULT_POSTMAN_API_BASE,
-    onToken: (token) => reporter.setSecret(token)
-  }) : tokenProvider;
   const telemetry = createTelemetryContext({ action: "postman-insights-onboarding-action", actionVersion: resolveActionVersion2(), logger: reporter });
-  telemetry.setTeamId(inputs.postmanTeamId || pmakIdentity?.teamId);
-  if (apiKey) {
-    reporter.setSecret(apiKey);
-  }
+  telemetry.setTeamId(inputs.postmanTeamId);
   let result;
   try {
+    let preflightPmakIdentity;
+    if (inputs.postmanApiKey) {
+      const validated = await validateApiKey(
+        inputs.postmanApiKey,
+        inputs.postmanApiBase || DEFAULT_POSTMAN_API_BASE
+      );
+      if (validated.valid) {
+        preflightPmakIdentity = { source: "pmak/me", teamId: validated.teamId };
+      } else if (!inputs.createApiKey) {
+        throw new Error(
+          "postman-api-key is invalid or expired. Provide a valid key, or set create-api-key=true to opt in to durable Bifrost API-key creation."
+        );
+      }
+    } else if (!inputs.createApiKey) {
+      throw new Error(
+        "postman-api-key is required for application binding. Provide a valid key, or set create-api-key=true to opt in to durable Bifrost API-key creation."
+      );
+    }
     await runCredentialPreflightForInputs(
       inputs,
-      pmakIdentity,
+      preflightPmakIdentity,
       reporter,
       void 0,
-      activeTokenProvider.current()
+      tokenProvider.current()
     );
+    const { apiKey, teamId, pmakIdentity } = await resolveApiKeyAndTeamId(inputs, preliminaryClient, reporter);
+    telemetry.setTeamId(inputs.postmanTeamId || pmakIdentity?.teamId);
+    reporter.setSecret(apiKey);
+    const activeTokenProvider = apiKey !== inputs.postmanApiKey ? new AccessTokenProvider({
+      accessToken: tokenProvider.current(),
+      apiKey,
+      apiBaseUrl: inputs.postmanApiBase || DEFAULT_POSTMAN_API_BASE,
+      onToken: (token) => reporter.setSecret(token)
+    }) : tokenProvider;
+    if (pmakIdentity?.teamId !== preflightPmakIdentity?.teamId) {
+      await runCredentialPreflightForInputs(
+        inputs,
+        pmakIdentity,
+        reporter,
+        void 0,
+        activeTokenProvider.current()
+      );
+    }
     const client = createInsightsBifrostClient(inputs, activeTokenProvider, teamId, apiKey);
     result = await (runtime.executeOnboarding ?? runOnboarding)(
       inputs,
@@ -23014,7 +23503,6 @@ async function runCli(argv = process.argv.slice(2), runtime = {}) {
   const jsonOutput = JSON.stringify(outputs, null, 2);
   await writeOptionalFile(config.resultJsonPath, jsonOutput);
   await writeOptionalFile(config.dotenvPath, toDotenv(outputs));
-  const writeStdout = runtime.writeStdout ?? ((chunk) => process.stdout.write(chunk));
   writeStdout(`${jsonOutput}
 `);
 }