@postman/sdk-config 0.12.0 → 0.14.0

package/README.md

@@ -75,15 +75,27 @@ if (!result.success) {
 SDK Config objects are strict. Unknown fields, duplicate language targets, incompatible package
 publication settings, and non-exact generator versions are rejected. npm and crates use
 `output.publish.token`, PyPI and Maven use flat `username` and `password` fields, and Maven may also
-use a complete `signature` object. Configure these fields with environment expressions such as
+use a complete `signature` object. NuGet and RubyGems use `output.publish.apiKey` to name the
+repository secret that the generated release workflow reads the API key from, such as
+`${MY_NUGET_KEY}`. That value is a secret name, never the key itself. Configure these fields with
+environment expressions such as
 `${NPM_TOKEN}` rather than literal credentials. Clients must resolve and transport credentials using
 a dedicated secret channel and remove them from generation payloads, logs, and stored artifacts.
-Fern migration preserves a credential only when the raw `generators.yml` value is exactly an
-environment expression; normalized, resolved, or literal values are omitted with a warning.
+NuGet and RubyGems may instead set `output.publish.trustedPublishing`, which authenticates the
+release workflow with a short-lived OIDC token the registry verifies against the repository. There is
+then no API key secret to name, so `apiKey` and `trustedPublishing` cannot both be set.
 
-CLI targets may also declare `output.distribution` (Homebrew and Scoop channels) and npm
-publication. Distribution credentials are GitHub Actions secret **names**, not environment
-expressions: clients must not resolve them or send them through the publish-credential channel. See
+Fern migration preserves a credential only when the raw `generators.yml` value is exactly an
+environment expression; normalized, resolved, or literal values are omitted with a warning. A GitHub
+NuGet target whose `api-key` names no secret gets `${NUGET_API_TOKEN}`, the secret Fern's generated
+workflow reads in that case, and no warning, because publishing keeps working unchanged. Fern states
+trusted publishing through the same `api-key` field, as `OIDC` or `<USE_OIDC>`, and migration maps
+either to `trustedPublishing: true` rather than dropping it.
+
+CLI targets may also declare `output.distribution` (Homebrew and Scoop channels and
+`githubAttestations` for release build provenance) and npm publication. Distribution credentials are
+GitHub Actions secret **names**, not environment expressions: clients must not resolve them or send
+them through the publish-credential channel. See
 [CLI distribution and npm publication](src/sdk-config/v1/README.md#cli-distribution-and-npm-publication).
 Call `getSdkConfigV1Diagnostics` after validation to surface non-fatal warnings.
 

package/dist/index.cjs

@@ -514,7 +514,10 @@ var cliDistributionConfigSchema = zod.z.strictObject({
     "A GitHub App used to mint short-lived tokens for every channel without its own tokenSecretName."
   ),
   homebrew: cliDistributionHomebrewSchema.optional().describe("Publishes a Homebrew formula to a tap repository on each tagged release."),
-  scoop: cliDistributionScoopSchema.optional().describe("Publishes a Scoop manifest to a bucket repository on each tagged release.")
+  scoop: cliDistributionScoopSchema.optional().describe("Publishes a Scoop manifest to a bucket repository on each tagged release."),
+  githubAttestations: zod.z.union([zod.z.literal("auto"), zod.z.boolean()], { error: 'must be "auto", true, or false' }).optional().describe(
+    'Whether the generated release workflow attests build provenance. "auto" (the generator default) attests only on public repositories; true always attests, for private repositories on GitHub Enterprise Cloud; false omits the attestation step and its permissions.'
+  )
 }).superRefine((distribution, context) => {
   if (distribution.homebrew !== void 0 || distribution.scoop !== void 0) {
     return;
@@ -527,6 +530,9 @@ var cliDistributionConfigSchema = zod.z.strictObject({
     });
     return;
   }
+  if (distribution.githubAttestations !== void 0) {
+    return;
+  }
   context.addIssue({
     code: "custom",
     message: "distribution must configure at least one channel: homebrew or scoop"
@@ -538,14 +544,17 @@ var CLI_DISTRIBUTION_NON_RELEASE_MODE_CODE = "CLI_DISTRIBUTION_NON_RELEASE_MODE"
 var nonReleaseGithubModes = /* @__PURE__ */ new Set(["pull-request", "push", "commit"]);
 function cliDistributionModeDiagnostic(output, outputPath) {
   const mode = output?.github?.mode;
-  if (output?.distribution === void 0 || mode === void 0 || !nonReleaseGithubModes.has(mode)) {
+  const distribution = output?.distribution;
+  if (distribution === void 0 || mode === void 0 || !nonReleaseGithubModes.has(mode)) {
     return void 0;
   }
+  const hasChannel = distribution.homebrew !== void 0 || distribution.scoop !== void 0;
+  const consequence = hasChannel ? "Homebrew and Scoop publish only after a semantic-version tag is pushed to the repository." : "the release workflow, including its githubAttestations setting, runs only after a semantic-version tag is pushed to the repository.";
   return {
     code: CLI_DISTRIBUTION_NON_RELEASE_MODE_CODE,
     severity: "warning",
     path: [...outputPath, "github", "mode"],
-    reason: `GitHub mode "${mode}" does not create a release tag, so Homebrew and Scoop publish only after a semantic-version tag is pushed to the repository.`,
+    reason: `GitHub mode "${mode}" does not create a release tag, so ${consequence}`,
     suggestedAction: 'Use mode "release" or "commit-and-release", or push a version tag after merging generated changes.'
   };
 }
@@ -980,6 +989,7 @@ var DISTRIBUTION_KEYS = {
   homebrew: { tap: "tap", formula: "formula", tokenEnvironmentVariable: "tokenSecretName" },
   scoop: { bucket: "bucket", tokenEnvironmentVariable: "tokenSecretName" }
 };
+var DISTRIBUTION_SCALAR_KEYS = ["githubAttestations"];
 function mapCliDistribution(config, state, basePath, targetIndex) {
   if (!Object.hasOwn(config, "distribution")) return;
   const raw = config.distribution;
@@ -1026,6 +1036,11 @@ function translateDistribution(distribution, path) {
     }
     value[block] = translatedBlock;
   }
+  for (const key of DISTRIBUTION_SCALAR_KEYS) {
+    if (!Object.hasOwn(distribution, key)) continue;
+    value[key] = distribution[key];
+    consumedPaths.push([...path, key]);
+  }
   return { value, consumedPaths, legacyKeys };
 }
 function invalidDistributionDiagnostic(issue, path, legacyKeys, targetIndex) {
@@ -1165,6 +1180,7 @@ function mapOutput(generator, language, index) {
         output.publishV2,
         rawOutput,
         language,
+        "zip",
         [...outputPath, "publishV2"],
         state,
         index
@@ -1186,6 +1202,7 @@ function mapOutput(generator, language, index) {
         output.registryOverrides,
         rawOutput,
         language,
+        "zip",
         [...outputPath, "registryOverrides"],
         state,
         index
@@ -1213,7 +1230,14 @@ function mapOutput(generator, language, index) {
   }
 }
 function sanitizeNormalizedOutput(output, rawOutput, state, index) {
-  const publish = output.publish ? sanitizePublishConfig(output.publish, output.publish, rawOutput, state, index) : void 0;
+  const publish = output.publish ? sanitizePublishConfig(
+    output.publish,
+    output.publish,
+    rawOutput,
+    output.delivery,
+    state,
+    index
+  ) : void 0;
   const publishShape = publish ? { publish } : {};
   if (output.delivery !== "github") return { ...output, ...publishShape };
   const { credentials, ...github } = output.github;
@@ -1240,13 +1264,22 @@ function githubOutput(value, publishInfo, rawOutput, language, sourcePath, state
     );
   consume(state, [...sourcePath, "owner"]);
   consume(state, [...sourcePath, "repo"]);
-  const publication = publishInfo ? mapPublication(publishInfo, rawOutput, language, [...sourcePath, "publishInfo"], state, index) : void 0;
+  const publication = publishInfo ? mapPublication(
+    publishInfo,
+    rawOutput,
+    language,
+    "github",
+    [...sourcePath, "publishInfo"],
+    state,
+    index
+  ) : void 0;
   const type = stringValue(value.type);
   const licensePackage = mapGithubLicense(value.license, [...sourcePath, "license"], state);
   const reviewers = mapReviewers(value.reviewers, [...sourcePath, "reviewers"], state);
   if (type) consume(state, [...sourcePath, "type"]);
   if (typeof value.makePr === "boolean") consume(state, [...sourcePath, "makePr"]);
-  if (value.workflows === true) consume(state, [...sourcePath, "workflows"]);
+  const workflows = typeof value.workflows === "boolean" ? value.workflows : void 0;
+  if (workflows !== void 0) consume(state, [...sourcePath, "workflows"]);
   if (stringValue(value.host)) consume(state, [...sourcePath, "host"]);
   if (stringValue(value.branch)) consume(state, [...sourcePath, "branch"]);
   consumeCredentialObject(value.credentials, [...sourcePath, "credentials"], state);
@@ -1266,7 +1299,8 @@ function githubOutput(value, publishInfo, rawOutput, language, sourcePath, state
         ...optional("host", stringValue(value.host)),
         ...optional("branch", stringValue(value.branch)),
         mode: value.makePr === true || type === "pullRequest" ? "pull-request" : type === "push" ? "push" : "release",
-        ...optional("reviewers", reviewers)
+        ...optional("reviewers", reviewers),
+        ...workflows === false ? { workflows } : {}
       },
       ...publication ? { publish: publication.publish } : {}
     },
@@ -1333,7 +1367,7 @@ function reviewerNames(value, expectedType, sourcePath, state) {
   });
   return names.length ? names : void 0;
 }
-function mapPublication(value, rawOutput, language, sourcePath, state, index) {
+function mapPublication(value, rawOutput, language, delivery, sourcePath, state, index) {
   if (!isObject(value))
     fail(
       "FERN_PUBLICATION_INVALID",
@@ -1354,6 +1388,7 @@ function mapPublication(value, rawOutput, language, sourcePath, state, index) {
     compact({ registry, url: registryUrl }),
     nested,
     rawOutput,
+    delivery,
     state,
     index
   );
@@ -1374,7 +1409,7 @@ function mapPublication(value, rawOutput, language, sourcePath, state, index) {
     ...packageName || Object.keys(metadata).length ? { package: { ...optional("packageName", packageName), ...metadata } } : {}
   };
 }
-function sanitizePublishConfig(publish, resolvedPublication, rawOutput, state, index) {
+function sanitizePublishConfig(publish, resolvedPublication, rawOutput, delivery, state, index) {
   const rawPublication = rawOutput?.location === publish.registry ? rawOutput : void 0;
   const rawPath = ["group", "generators", index, "output"];
   if (publish.registry === "npm" || publish.registry === "crates") {
@@ -1470,6 +1505,33 @@ function sanitizePublishConfig(publish, resolvedPublication, rawOutput, state, i
       signature
     });
   }
+  if (publish.registry === "nuget" || publish.registry === "rubygems") {
+    const apiKey = mapApiKeyExpression(
+      publish.registry,
+      rawPublication,
+      resolvedPublication,
+      rawPath,
+      state,
+      index,
+      fernDefaultApiKey(publish.registry, rawOutput, delivery)
+    );
+    warnForUnexpectedCredentialFields(
+      rawPublication,
+      resolvedPublication,
+      ["apiKey"],
+      rawPath,
+      state,
+      index
+    );
+    return compact({
+      registry: publish.registry,
+      url: publish.url,
+      releaseBranch: publish.releaseBranch,
+      tolerateRepublish: publish.tolerateRepublish,
+      apiKey,
+      trustedPublishing: usesTrustedPublishing(rawPublication) || void 0
+    });
+  }
   warnForUnrepresentableCredentials(rawPublication, resolvedPublication, rawPath, state, index);
   return compact({
     registry: publish.registry,
@@ -1478,11 +1540,19 @@ function sanitizePublishConfig(publish, resolvedPublication, rawOutput, state, i
     tolerateRepublish: publish.tolerateRepublish
   });
 }
-function mapLegacyPublication(value, rawOutput, language, sourcePath, state, index) {
+function mapLegacyPublication(value, rawOutput, language, delivery, sourcePath, state, index) {
   const registry = defaultRegistry(language, sourcePath, index);
   const overrides = isObject(value) ? value : {};
   const override = isObject(overrides[registry]) ? overrides[registry] : {};
-  return mapPublication(override, rawOutput, language, [...sourcePath, registry], state, index);
+  return mapPublication(
+    override,
+    rawOutput,
+    language,
+    delivery,
+    [...sourcePath, registry],
+    state,
+    index
+  );
 }
 function mapCredentialExpression(rawPublication, resolvedPublication, field, rawPath, state, index) {
   const rawValue = rawPublication?.[field];
@@ -1497,6 +1567,45 @@ function mapCredentialExpression(rawPublication, resolvedPublication, field, raw
   }
   return void 0;
 }
+var TRUSTED_PUBLISHING_VALUES = /* @__PURE__ */ new Set(["OIDC", "<USE_OIDC>"]);
+function rawApiKeyValue(raw) {
+  return raw?.apiKey ?? raw?.["api-key"];
+}
+function usesTrustedPublishing(rawPublication) {
+  const rawValue = rawApiKeyValue(rawPublication);
+  return typeof rawValue === "string" && TRUSTED_PUBLISHING_VALUES.has(rawValue);
+}
+function mapApiKeyExpression(registry, rawPublication, resolvedPublication, rawPath, state, index, defaultSecretName) {
+  const rawValue = rawApiKeyValue(rawPublication);
+  if (isEnvironmentExpression(rawValue)) return rawValue;
+  if (usesTrustedPublishing(rawPublication)) return void 0;
+  if (defaultSecretName !== void 0) return defaultSecretName;
+  if (rawValue === void 0 && !hasResolvedCredential(resolvedPublication, "apiKey")) {
+    return void 0;
+  }
+  addCredentialDiagnostic(
+    state,
+    [...rawPath, "apiKey"],
+    ["targets", index, "output", "publish", "apiKey"],
+    apiKeyOmissionReason(registry)
+  );
+  return void 0;
+}
+function apiKeyOmissionReason(registry) {
+  const label = registry === "nuget" ? "NuGet" : "RubyGems";
+  return `Fern ${label} apiKey is not an exact environment expression naming a secret`;
+}
+var FERN_DEFAULT_NUGET_API_KEY = "${NUGET_API_TOKEN}";
+function fernDefaultApiKey(registry, rawOutput, delivery) {
+  if (registry !== "nuget" || delivery !== "github" || rawOutput?.location !== "nuget") {
+    return void 0;
+  }
+  const rawApiKey = rawApiKeyValue(rawOutput);
+  if (typeof rawApiKey === "string" && TRUSTED_PUBLISHING_VALUES.has(rawApiKey)) {
+    return void 0;
+  }
+  return FERN_DEFAULT_NUGET_API_KEY;
+}
 function mapPypiCredentialExpressions(rawPublication, resolvedPublication, rawPath, state, index) {
   const rawToken = rawPublication?.token;
   if (isEnvironmentExpression(rawToken)) {
@@ -2212,6 +2321,29 @@ var mavenSignatureSchema = zod.z.strictObject({
     "The armored secret key, or an environment expression that resolves to it."
   )
 });
+function apiKeySecretSchema(registry, example) {
+  return nonEmptyStringSchema.regex(
+    /^\$\{[A-Za-z_][A-Za-z0-9_]*\}$/,
+    `${registry} apiKey must be an environment expression naming a secret, such as ${example}`
+  );
+}
+function apiKeySecretDescription(registry, example) {
+  return `An environment expression naming the repository secret that the generated release workflow reads the ${registry} API key from, such as ${example}. This is a secret name, never the key itself.`;
+}
+function trustedPublishingSchema(registry) {
+  return zod.z.boolean().optional().describe(
+    `Whether ${registry} publication uses trusted publishing (OIDC) instead of an API key secret.`
+  );
+}
+function refineApiKeyAgainstTrustedPublishing(publish, context) {
+  if (publish.trustedPublishing === true && publish.apiKey !== void 0) {
+    context.addIssue({
+      code: "custom",
+      message: "apiKey must be omitted when trustedPublishing is true",
+      path: ["apiKey"]
+    });
+  }
+}
 var commonPublishShape = {
   url: nonEmptyStringSchema.optional().describe("A custom package registry URL."),
   releaseBranch: nonEmptyStringSchema.optional().describe("The branch used by generated package release workflows."),
@@ -2247,12 +2379,16 @@ var sdkConfigV1PublishConfigSchema = zod.z.discriminatedUnion("registry", [
   }),
   zod.z.strictObject({
     registry: zod.z.literal("nuget").describe("Publishes the package to a NuGet-compatible registry."),
+    apiKey: apiKeySecretSchema("NuGet", "${NUGET_API_KEY}").optional().describe(apiKeySecretDescription("NuGet", "${NUGET_API_KEY}")),
+    trustedPublishing: trustedPublishingSchema("NuGet"),
     ...commonPublishShape
-  }),
+  }).superRefine(refineApiKeyAgainstTrustedPublishing),
   zod.z.strictObject({
     registry: zod.z.literal("rubygems").describe("Publishes the package to a RubyGems-compatible registry."),
+    apiKey: apiKeySecretSchema("RubyGems", "${RUBYGEMS_API_KEY}").optional().describe(apiKeySecretDescription("RubyGems", "${RUBYGEMS_API_KEY}")),
+    trustedPublishing: trustedPublishingSchema("RubyGems"),
     ...commonPublishShape
-  }),
+  }).superRefine(refineApiKeyAgainstTrustedPublishing),
   zod.z.strictObject({
     registry: zod.z.literal("crates").describe("Publishes the crate to a Cargo-compatible registry."),
     token: nonEmptyStringSchema.optional().describe("The Cargo registry token, or an environment expression that resolves to it."),
@@ -2286,7 +2422,10 @@ var githubOutputSchema = zod.z.strictObject({
   mode: zod.z.enum(["release", "pull-request", "push", "commit", "commit-and-release"]).optional().describe("How generated changes are delivered to the repository."),
   reviewers: reviewersSchema.optional().describe("Reviewers requested for generated pull requests."),
   credentials: githubCredentialsSchema.optional().describe("Credentials used to authenticate GitHub delivery."),
-  privateRepository: zod.z.boolean().optional().describe("Whether the destination repository is private.")
+  privateRepository: zod.z.boolean().optional().describe("Whether the destination repository is private."),
+  workflows: zod.z.boolean().optional().describe(
+    "Whether generated .github/workflows files are delivered. Defaults to true. When false, newly generated workflow files are skipped and existing ones in the repository are left untouched."
+  )
 });
 var filesOutputSchema = zod.z.strictObject({
   delivery: zod.z.literal("files").describe("Writes the generated SDK to a directory."),
@@ -2310,7 +2449,7 @@ var sdkConfigV1OutputConfigSchema = zod.z.discriminatedUnion(
 );
 var cliDistributionShape = {
   distribution: cliDistributionConfigSchema.optional().describe(
-    "CLI release channels published by the generated release workflow; credentials are GitHub Actions secret names."
+    "CLI release channels and build attestation settings for the generated release workflow; credentials are GitHub Actions secret names."
   )
 };
 function rejectDistributionWithoutGithub(output, context) {
@@ -2356,6 +2495,9 @@ var apiImportSettingsSchema = zod.z.strictObject({
   discriminatedUnionV2: zod.z.boolean().optional().describe("Whether oneOf and anyOf schemas use the newer discriminator inference rules."),
   undiscriminatedUnionsWithLiterals: zod.z.boolean().optional().describe("Whether literal-bearing unions remain undiscriminated during import."),
   inlineAllOfSchemas: zod.z.boolean().optional().describe("Whether schemas composed with allOf are inlined when possible."),
+  inferDiscriminatedUnionBaseProperties: zod.z.boolean().optional().describe(
+    "Whether properties every discriminated-union variant shares are lifted onto the union."
+  ),
   resolveSchemaCollisions: zod.z.boolean().optional().describe("Whether colliding imported schema names are resolved automatically."),
   asyncApiMessageNaming: zod.z.enum(["v1", "v2"]).optional().describe("The naming strategy used for messages imported from AsyncAPI."),
   defaultIntegerFormat: zod.z.enum(["int32", "int64", "uint32", "uint64"]).optional().describe("The integer format used when a schema does not declare one.")
@@ -2574,7 +2716,7 @@ var pythonGenerationConfigSchema = zod.z.strictObject({
   additionalInitExports: zod.z.array(additionalInitExportSchema).optional().describe("Additional names re-exported from the package initializer.")
 });
 var rubyGenerationConfigSchema = zod.z.strictObject({
-  requirePaths: zod.z.array(nonEmptyStringSchema).optional().describe("Ruby load paths included in the generated gem specification.")
+  requirePaths: zod.z.array(nonEmptyStringSchema).optional().describe("Files the generated entry file loads with `require`.")
 });
 var rustGenerationConfigSchema = zod.z.strictObject({
   /**
@@ -3305,7 +3447,12 @@ function mapCommonConfig(language, config, state, client, generation, packageCon
   }
   const pythonClient = language === "python" ? takeObject(config, ["client"], state, basePath) : void 0;
   const typescriptNaming = language === "typescript" || language === "mcp" ? takeObject(config, ["naming"], state, basePath) : void 0;
-  const directClientName = takeString(config, ["clientName", "clientClassName"], state, basePath);
+  const directClientName = takeString(
+    config,
+    language === "ruby" ? ["clientName"] : ["clientName", "clientClassName"],
+    state,
+    basePath
+  );
   const nestedClientName = pythonClient ? takeString(pythonClient.value, ["className"], state, pythonClient.path) : typescriptNaming ? takeString(typescriptNaming.value, ["client"], state, typescriptNaming.path) : language === "ruby" ? (
     // Fern's Ruby generator renames the root client class (`Auth0::Management`) with it.
     takeString(config, ["clientModuleName"], state, basePath)
@@ -4355,6 +4502,7 @@ var publishConfigSchema = zod.z.discriminatedUnion("registry", [
   zod.z.strictObject({
     registry: zod.z.literal("rubygems").describe("Publishes the package to a RubyGems-compatible registry."),
     apiKeyEnvironmentVariable: nonEmptyStringSchema.optional().describe("The environment variable containing the RubyGems API key."),
+    ...trustedPublishingShape,
     ...commonPublishShape2
   }),
   zod.z.strictObject({
@@ -4411,6 +4559,10 @@ var githubOutputSchema2 = zod.z.strictObject({
   /** Raw GitHub credentials. These values can be sensitive and must be handled as secrets. */
   credentials: registryCredentialsSchema.optional().describe("Resolved GitHub credentials."),
   privateRepository: zod.z.boolean().optional().describe("Whether the destination repository is private."),
+  /** Whether generated `.github/workflows` files are delivered. If omitted, they are (true). */
+  workflows: zod.z.boolean().optional().describe(
+    "Whether generated .github/workflows files are delivered. Defaults to true. When false, newly generated workflow files are skipped and existing ones in the repository are left untouched."
+  ),
   /** GitHub license block scoped to repository delivery. */
   license: githubLicenseSchema.optional().describe("License configuration for the destination repository."),
   /** GitHub replay control. If omitted, the external publisher applies its default behavior. */
@@ -4425,7 +4577,7 @@ var githubOutputSchema2 = zod.z.strictObject({
 var distributionShape = {
   /** Valid only for `cli` targets with GitHub delivery; secret names only, never values. */
   distribution: cliDistributionConfigSchema.optional().describe(
-    "CLI release channels published by the generated release workflow; credentials are GitHub Actions secret names."
+    "CLI release channels and build attestation settings for the generated release workflow; credentials are GitHub Actions secret names."
   )
 };
 var credentialResolutionShape = {