@halospv3/hce.shared-config 3.4.7 → 3.4.8-develop.1

package/mjs/dotnet/NugetRegistryInfo.mjs

@@ -1,5 +1,601 @@
-import{isError as e}from"../utils/isError.mjs";import{execAsync as t}from"../utils/execAsync.mjs";import{MSBuildEvaluationOutput as n,MSBuildProject as r,catchEBUSY as i}from"./MSBuildProject.mjs";import{getEnvVarValue as a}from"../utils/env.mjs";import{cwd as o,env as s}from"node:process";import{type as c}from"arktype";import*as l from"node:path";import{existsSync as u,writeFileSync as d}from"node:fs";import{writeFile as f}from"node:fs/promises";import{setTimeout as p}from"node:timers/promises";import{tmpdir as m}from"node:os";import{ok as h}from"node:assert/strict";import{config as g}from"@dotenvx/dotenvx";import{detectFile as _,detectFileSync as v}from"chardet";import y from"sanitize-filename";const b=l.join(m(),`HCE.Shared`,`.NET`,`Dummies`),x=`_OutputPackItems`;async function S(){if(s.GITHUB_OUTPUT===void 0||!u(s.GITHUB_OUTPUT)){let e=l.join(m(),`GITHUB_OUTPUT`);u(e)||await f(e,``),s.GITHUB_OUTPUT=e}let t=await _(s.GITHUB_OUTPUT),n=g({path:s.GITHUB_OUTPUT,override:!0,encoding:t??void 0,processEnv:{}});if(e(n.error))throw n.error;return n.parsed}function C(){if(s.GITHUB_OUTPUT===void 0||!u(s.GITHUB_OUTPUT)){let e=l.join(m(),`GITHUB_OUTPUT`);u(e)||d(e,``),s.GITHUB_OUTPUT=e}let e=v(s.GITHUB_OUTPUT),t=g({path:s.GITHUB_OUTPUT,override:!0,encoding:e??void 0,processEnv:{}});if(`error`in t)throw t.error;return t.parsed}function w(e){switch(!0){case e===void 0:return l.join(b,l.sep);case e instanceof r:return l.join(b,e.Properties.PackageId,l.sep);default:throw Error("The type of argument `project` must be `undefined` or `MSBuildProject`.")}}function T(e){let t=Object.freeze(e.map(e=>[e,a(e)]).filter(e=>e[1]!==void 0));if(t.length>0)return t}var E=class r{_canPushPackagesToSource=void 0;_project;_resolvedEnvVariable;_source;static DefaultTokenEnvVars=Object.freeze([`NUGET_TOKEN`]);static GetDirNameForSource(e){return y(e.replaceAll(/\/index.json$/g,``),{replacement:`_`})}constructor(e){let t=k.from(e);this._project=t.project;let n=T(t.tokenEnvVars);n&&(this._resolvedEnvVariable=n[0][0]),this._source=t.source}get project(){return this._project}get canPushPackagesToSource(){if(this._canPushPackagesToSource!==void 0)return this._canPushPackagesToSource;let e;if(this.resolvedEnvVariable!==void 0&&(e=D._GetTokenValue(this.resolvedEnvVariable)),e?.startsWith(`github_pat_`)){let e=`The value of the token in 'resolvedEnvVariable' ${String(this.resolvedEnvVariable)} begins with 'github_pat_', indicating it's a Fine-Grained token. At the time of writing, GitHub Fine-Grained tokens cannot push packages. If you believe this is statement is outdated, report the issue at https://github.com/halospv3/hce.shared/issues/new. For more information, see https://docs.github.com/en/packages/working-with-a-github-packages-registry/working-with-the-nuget-registry.`,t=Error(e);return this._canPushPackagesToSource=Promise.reject(t)}return this._canPushPackagesToSource=this.PackDummyPackage({}).then(async()=>await this._PushDummyPackages({apiKey:e})).then(e=>(h(e),!0))}get resolvedEnvVariable(){return this._resolvedEnvVariable}get source(){return this._source}static _GetTokenValue(e){c.string.assert(e);let t=a(e);if(t===void 0)throw Error(`\
-The environment variable ${e} was specified \
+import { isError } from "../utils/isError.mjs";
+import { execAsync } from "../utils/execAsync.mjs";
+import { MSBuildEvaluationOutput, MSBuildProject, catchEBUSY } from "./MSBuildProject.mjs";
+import { getEnvVarValue } from "../utils/env.mjs";
+import { cwd, env } from "node:process";
+import { type } from "arktype";
+import * as node_path from "node:path";
+import { existsSync, writeFileSync } from "node:fs";
+import { writeFile } from "node:fs/promises";
+import { setTimeout } from "node:timers/promises";
+import { tmpdir } from "node:os";
+import { ok } from "node:assert/strict";
+import { config } from "@dotenvx/dotenvx";
+import { detectFile, detectFileSync } from "chardet";
+import sanitizeFileName from "sanitize-filename";
+//#region src/dotnet/NugetRegistryInfo.ts
+const tmpDirNamespace = node_path.join(tmpdir(), "HCE.Shared", ".NET", "Dummies");
+const defaultNugetSource = "https://api.nuget.org/v3/index.json";
+const key_OutputPackItems = "_OutputPackItems";
+/**
+* Read the contents of $GITHUB_OUTPUT (if its value is a file path) or $TEMP/GITHUB_OUTPUT.
+* If the file doesn't exist, it is created.
+* @returns If successful, a promised object with a parsed key.
+*/
+async function getGithubOutput() {
+	if (env["GITHUB_OUTPUT"] === void 0 || !existsSync(env["GITHUB_OUTPUT"])) {
+		const githubOutputPath = node_path.join(tmpdir(), "GITHUB_OUTPUT");
+		if (!existsSync(githubOutputPath)) await writeFile(githubOutputPath, "");
+		env["GITHUB_OUTPUT"] = githubOutputPath;
+	}
+	const encoding = await detectFile(env["GITHUB_OUTPUT"]);
+	const envOutput = config({
+		path: env["GITHUB_OUTPUT"],
+		override: true,
+		encoding: encoding ?? void 0,
+		processEnv: {}
+	});
+	if (isError(envOutput.error)) throw envOutput.error;
+	return envOutput.parsed;
+}
+/**
+* Read the contents of $GITHUB_OUTPUT (if its value is a file path) or $TEMP/GITHUB_OUTPUT.
+* If the file doesn't exist, it is created.
+* @returns An object with a parsed key if successful.
+*/
+function getGithubOutputSync() {
+	if (env["GITHUB_OUTPUT"] === void 0 || !existsSync(env["GITHUB_OUTPUT"])) {
+		const githubOutputPath = node_path.join(tmpdir(), "GITHUB_OUTPUT");
+		if (!existsSync(githubOutputPath)) writeFileSync(githubOutputPath, "");
+		env["GITHUB_OUTPUT"] = githubOutputPath;
+	}
+	const encoding = detectFileSync(env["GITHUB_OUTPUT"]);
+	const envOutput = config({
+		path: env["GITHUB_OUTPUT"],
+		override: true,
+		encoding: encoding ?? void 0,
+		processEnv: {}
+	});
+	if ("error" in envOutput) throw envOutput.error;
+	return envOutput.parsed;
+}
+/**
+* Get HCE.Shared's temporary directory for .NET projects' dummy packages.
+* @param project The MSBuild project whose PackageId will be used to create a
+* directory for its dummy packages.
+* @returns a platform-specific path like
+* `${tmpdir()}/HCE.Shared/.NET/Dummies/${project.Properties.PackageId}` if
+* {@link project} is defined. Else `${tmpdir()}/HCE.Shared/.NET/Dummies`
+*/
+function getDummiesDir(project) {
+	switch (true) {
+		case project === void 0: return node_path.join(tmpDirNamespace, node_path.sep);
+		case project instanceof MSBuildProject: return node_path.join(tmpDirNamespace, project.Properties.PackageId, node_path.sep);
+		default: throw new Error("The type of argument `project` must be `undefined` or `MSBuildProject`.");
+	}
+}
+/**
+* Get the environment variables as key-value pairs.
+* @param tokenEnvVars The name of the environment variables whose values are
+* NuGet API keys.
+* @returns an array of key-value pairs of the given environment variables and
+* their values, filtered to only those whose values are not undefined.
+* @throws {Error} when none of the provided environment variables are defined.
+*/
+function _GetTokenEnvVariables(tokenEnvVars) {
+	const definedTokens = Object.freeze(tokenEnvVars.map((key) => [key, getEnvVarValue(key)]).filter((envVarTuple) => envVarTuple[1] !== void 0));
+	if (definedTokens.length > 0) return definedTokens;
+}
+var NugetRegistryInfo = class NugetRegistryInfo {
+	_canPushPackagesToSource = void 0;
+	_project;
+	_resolvedEnvVariable;
+	_source;
+	static DefaultTokenEnvVars = Object.freeze(["NUGET_TOKEN"]);
+	/**
+	* Convert a URL string to a filesystem folder name.
+	*
+	* Intended usage: modify the output path of `dotnet pack` based on the NuGet
+	* Source the package should be pushed to. This is extra work is usually
+	* unnecessary and you'd typically push the same file to multiple sources.
+	* This is for the edge-case scenario of creating multiple nupkgs and signing
+	* each one with a different certificate corresponding to a given NuGet
+	* Source. This is only useful if the Sources have different certificates
+	* registered for a given package/user/organization.
+	* @param source The URL of the NuGet Source
+	* @returns A string suitable for a local filesystem folder name, formatted as
+	* `${hostname}_${pathname.replace('/', '_')}`.
+	*/
+	static GetDirNameForSource(source) {
+		return sanitizeFileName(source.replaceAll(/\/index.json$/g, ""), { replacement: "_" });
+	}
+	/**
+	* Creates an instance of NugetRegistryInfo.\
+	* This class enables the ability to push a given {@link project}'s
+	* package(s) to the {@link source} of a given NuGet Source's API endpoint with
+	* a user-defined API key. This API key, herein referred to as a "token", is
+	* derived from the {@link tokenEnvVars} array. This array is iterated through
+	* until one of the items is discovered to be an existing environment variable
+	* (or is defined in a file named '.env' in the current working directory for
+	* LOCAL TESTING ONLY! Do NOT `git add` your private keys!).
+	* \
+	* WARNING:
+	* - The token value is stored privately within this class, but it is plain text.
+	* - This private key may be copied to command line strings stored in Semantic
+	*   Release's config object for later use by `@semantic-release/exec`.
+	* - Other EcmaScript modules can access the environment variable(s) and steal
+	*   your key. Be aware of malicious dependencies!
+	* @param opts The input type of {@link NRIOpts.from}
+	* @param opts.project The project whose package(s) will be
+	* pushed.\
+	* - Its {@link NugetProjectProperties#PackageId} will be read.\
+	* - Its {@link NugetProjectProperties#PackageVersion} will be overridden via CLI args when creating a dummy package. The real package's
+	* `PackageVersion` will *not* be overridden.
+	* @param [opts.tokenEnvVars] The environment variables
+	* whose values are tokens with permission to push a package to the NuGet
+	* package registry. The array is iterated through until one token is found.
+	* If none of the environment variables are defined, this constructor will
+	* throw an {@link Error}.
+	* @param [opts.source] A NuGet package registry's API endpoint URL or name. Default: 'https://api.nuget.org/v3/index.json'
+	*/
+	constructor(opts) {
+		const validOpts = NRIOpts.from(opts);
+		this._project = validOpts.project;
+		/**
+		* May throw! Assign key of the first key-value pair to
+		* {@link resolvedEnvVariable}
+		*/
+		const tokenVars = _GetTokenEnvVariables(validOpts.tokenEnvVars);
+		if (tokenVars) this._resolvedEnvVariable = tokenVars[0][0];
+		this._source = validOpts.source;
+	}
+	get project() {
+		return this._project;
+	}
+	/**
+	* This is not useful without it being executed as part of a Semantic Release
+	* plugin. Deferring this to `@semantic-release/exec`'s prepareCmd is possible,
+	* but impractical. You'd need to configure prepareCmd to invoke something
+	* like `node customScriptFile.mjs`. It's not worth the hassle.
+	* @returns `true` if the token can be used to push nupkg to the given Nuget registry
+	* @throws {TypeError | Error | import('../utils/execAsync.js').ChildProcessSpawnException }
+	* - {@link Error} | {@link module:utils/execAsync:ChildProcessSpawnException ChildProcessSpawnException}
+	*   - The token is invalid, of the wrong token type, or lacks permission to push packages
+	*   - The URL does not exist or a connection could not be established
+	*   - The command line string is malformed.
+	* @deprecated Call during the `verifyConditions` step of Semantic Release! Additionally, {@link GetIsNextVersionAlreadyPublishedCommand}'s return value should be assigned to `prepareCmd` to prevent package version collision errors.
+	*/
+	get canPushPackagesToSource() {
+		if (this._canPushPackagesToSource !== void 0) return this._canPushPackagesToSource;
+		let tokenValue;
+		if (this.resolvedEnvVariable !== void 0) tokenValue = NRI._GetTokenValue(this.resolvedEnvVariable);
+		if (tokenValue?.startsWith("github_pat_")) {
+			const errMsg = `The value of the token in 'resolvedEnvVariable' ${String(this.resolvedEnvVariable)} begins with 'github_pat_', indicating it's a Fine-Grained token. At the time of writing, GitHub Fine-Grained tokens cannot push packages. If you believe this is statement is outdated, report the issue at https://github.com/halospv3/hce.shared/issues/new. For more information, see https://docs.github.com/en/packages/working-with-a-github-packages-registry/working-with-the-nuget-registry.`;
+			const err = new Error(errMsg);
+			return this._canPushPackagesToSource = Promise.reject(err);
+		}
+		return this._canPushPackagesToSource = this.PackDummyPackage({}).then(async () => await this._PushDummyPackages({ apiKey: tokenValue })).then((execAsyncReturn) => {
+			ok(execAsyncReturn);
+			return true;
+		});
+	}
+	/**
+	* The first environment variable found to have a defined value. Set by
+	* {@link _GetTokenEnvVariables} in the constructor.
+	* @returns The first environment variable found to have a defined value.
+	*/
+	get resolvedEnvVariable() {
+		return this._resolvedEnvVariable;
+	}
+	get source() {
+		return this._source;
+	}
+	/**
+	* Get the API token from {@link NugetRegistryInfo#resolvedEnvVariable}
+	* @param resolvedEnvVariable The name of the environment variable(s) whose
+	* value is a NuGet API key. Typically, the value of
+	* {@link NugetRegistryInfo#resolvedEnvVariable}.
+	* @returns The value of the first defined environment variable.
+	* @throws {Error} when none of the provided environment variables are defined.
+	*/
+	static _GetTokenValue(resolvedEnvVariable) {
+		type.string.assert(resolvedEnvVariable);
+		const tokenValue = getEnvVarValue(resolvedEnvVariable);
+		if (tokenValue === void 0) throw new Error(`\
+The environment variable ${resolvedEnvVariable} was specified \
 as the source of the token to push a NuGet package, \
-but the environment variable is empty or undefined.`);return t}static PackPackagesOptionsType=Object.freeze(c({"propertyOverrides?":c(`Record<string,string>`),"artifactsPath?":`string`,"configuration?":`"Release" | "Debug"`,"disableBuildServers?":`boolean`,"force?":`boolean`,"includeSource?":`boolean`,"includeSymbols?":`boolean`,"interactive?":`boolean`,"noBuild?":`boolean`,"noLogo?":`boolean`,"noRestore?":`boolean`,"output?":`string`,"runtime?":`string`,"serviceable?":`boolean`,"terminalLogger?":`"auto" | "on" | "off"`,"useCurrentRuntime?":`boolean`,"verbosity?":`"quiet" | "minimal" | "normal" | "detailed" | "diagnostic"`,"versionSuffix?":`string`,"-GetItem?":c.string.array().readonly().or(`string[]`)}));static PackDummyPackagesOptionsType=this.PackPackagesOptionsType.omit(`output`);GetPackCommand(e,t=!1,n=!1){let i=D.PackPackagesOptionsType.from(e);c.boolean.assert(t),c.boolean.assert(n),i.output??=l.join(o(),`publish`),t&&(i.output=l.join(i.output,r.GetDirNameForSource(this.source),l.sep)),n&&(i.output=l.join(i.output,this._project.Properties.PackageId,l.sep));let a=[`dotnet`,`pack`,`"${this._project.Properties.MSBuildProjectFullPath}"`];if(i.artifactsPath!==void 0&&a.push(`--artifactsPath`,`"${i.artifactsPath}"`),i.configuration!==void 0&&a.push(`--configuration`,i.configuration),i.disableBuildServers===!0&&a.push(`--disable-build-servers`),i.force===!0&&a.push(`--force`),i.includeSource===!0&&a.push(`--include-source`),i.includeSymbols===!0&&a.push(`--include-symbols`),i.interactive===!0&&a.push(`--interactive`),i.noBuild===!0&&a.push(`--no-build`),i.noLogo===!0&&a.push(`--nologo`),i.noRestore===!0&&a.push(`--no-restore`),i.runtime!==void 0&&a.push(`--runtime`,i.runtime),i.serviceable===!0&&a.push(`--serviceable`),i.terminalLogger!==void 0&&a.push(`--tl`,i.terminalLogger),i.useCurrentRuntime===!0&&a.push(`--use-current-runtime`),i.verbosity!==void 0&&a.push(`--verbosity`,i.verbosity),i.versionSuffix!==void 0&&a.push(`--version-suffix`,i.versionSuffix),i.propertyOverrides){let e=`-p:`+Object.entries(i.propertyOverrides).map(e=>`${e[0]}=${e[1]}`).join(`;`);a.push(`"${e}"`)}return i[`-GetItem`]&&i[`-GetItem`].length>0&&a.push(`-GetItem:${i[`-GetItem`].join(`,`)}`),a.push(`-o`,`"${i.output}"`),a.join(` `)}async _PackPackages(e,r=!1,a=!1){e[`-GetItem`]=[...e[`-GetItem`]??[],x];let o=this.GetPackCommand(e,r,a),s;for(;s===void 0;)s=await p(1e3,t(o,!0)).then(async e=>await e).catch(i);return new n(s.stdout).Items?.[x]?.filter(e=>e.Extension!==`.nuspec`).map(e=>e.FullPath)??[]}async PackDummyPackage(e){let r=this.GetPackCommand({...e,output:w(this._project),propertyOverrides:{...e.propertyOverrides,Version:`0.0.1-DUMMY`,UpdateVersionProperties:`false`},"-GetItem":[...e[`-GetItem`]??[],x]},!0),a;for(;a===void 0;)a=await p(1e3,t(r,!0)).then(async e=>await e).catch(i);return new n(a.stdout).Items?.[x]?.filter(e=>e.Extension!==`.nuspec`).map(e=>e.FullPath)??[]}static PushPackagesOptionsType=Object.freeze(c({root:`string`,"apiKey?":`string`,"configFile?":`string`,"disableBuffering?":`boolean`,"forceEnglishOutput?":`boolean`,"interactive?":`boolean`,"noServiceEndpoint?":`boolean`,"noSymbols?":`boolean`,"skipDuplicate?":`boolean`,"source?":`string`,"symbolApiKey?":`string`,"symbolSource?":`string`,"timeout?":`number`}));static PushDummyPackagesOptionsType=r.PushPackagesOptionsType.merge({skipDuplicate:`true = true`}).omit(`root`);GetPushCommand(e,t=!1,n=!1){let i=D.PushPackagesOptionsType.from(e);c.boolean.assert(t),c.boolean.assert(n),i.root=i.root===``?`${o()}/publish`:i.root,t&&(i.root=l.join(i.root,r.GetDirNameForSource(this.source),l.sep)),n&&(i.root=l.join(i.root,this._project.Properties.PackageId,l.sep));let a=[`dotnet`,`nuget`,`push`,`"${l.join(i.root,`*.nupkg`)}"`];return this.resolvedEnvVariable&&(i.apiKey??=D._GetTokenValue(this.resolvedEnvVariable)),i.apiKey&&i.apiKey!==``&&a.push(`--api-key`,i.apiKey),i.configFile&&a.push(`--configfile`,i.configFile),i.disableBuffering===!0&&a.push(`--disable-buffering`),i.forceEnglishOutput===!0&&a.push(`--force-english-output`),i.interactive===!0&&a.push(`--interactive`),i.noServiceEndpoint===!0&&a.push(`--no-service-endpoint`),i.noSymbols===!0&&a.push(`--no-symbols`),i.skipDuplicate===!0&&a.push(`--skip-duplicate`),i.source??=this.source,a.push(`--source`,i.source),i.symbolApiKey!==void 0&&a.push(`--symbol-api-key`,i.symbolApiKey),i.symbolSource!==void 0&&a.push(`--symbol-source`,i.symbolSource),i.timeout!==void 0&&a.push(`--timeout`,i.timeout.toString()),a.join(` `)}async _PushPackages(n,r=!1,i=!1){await t(this.GetPushCommand(n,r,i),!0).catch(t=>{let r=e(t)?t:Error(JSON.stringify(t));throw n.apiKey?j(r,n.apiKey):r})}GetPushDummyCommand(e){return this.GetPushCommand({...D.PushDummyPackagesOptionsType.from(e),root:w(this._project)},!0)}async _PushDummyPackages(n){return await t(this.GetPushDummyCommand(n),!0).catch(t=>{let r=e(t)?t:Error(String(t));throw n.apiKey?j(r,n.apiKey):r})}static _NugetSearchReturnTypes={ExactMatch:{v2:c({version:`2`,problems:`unknown[]`,searchResult:[{sourceName:`string`,packages:c({id:`string`,version:c.keywords.string.semver}).array()}]})}};static _ParseNugetSearchReturn=c(`string.json.parse`).to(this._NugetSearchReturnTypes.ExactMatch.v2);static async IsNextVersionAlreadyPublished(e,n,r){if(r===``)throw Error(`The value of nextVersion is empty`);return await t(`dotnet package search --format JSON --exact-match --source ${e} --prerelease ${n}`,!0).then(e=>e.stdout).then(e=>this._ParseNugetSearchReturn(e)).then(e=>e instanceof c.errors?e.throw():e).then(e=>e.searchResult).then(e=>e[0].packages).then(e=>e.find(e=>e.version===c(`string.semver`).from(r))).then(e=>e!==void 0)}GetIsNextVersionAlreadyPublishedCommand(){return C(),`node ${l.join(import.meta.dirname,`./IsNextVersionAlreadyPublished.cli.js`)} --packageId ${this._project.Properties.PackageId} --source ${this.source}`}};const D=E,O=c({project:c.instanceOf(r).or(c.instanceOf(r).readonly()),source:c.string,tokenEnvVars:c.string.array().readonly()}),k=O.merge({tokenEnvVars:O.get(`tokenEnvVars`).default(()=>E.DefaultTokenEnvVars),source:O.get(`source`).default(()=>`https://api.nuget.org/v3/index.json`)});function A(e,t){return e.replaceAll(t,`***`)}function j(e,t){return Object.assign(e,JSON.parse(A(JSON.stringify({...e,message:e.message,stack:e.stack}),t)))}export{k as NRIOpts,O as NRIOptsBase,E as NugetRegistryInfo,S as getGithubOutput,C as getGithubOutputSync};
+but the environment variable is empty or undefined.`);
+		return tokenValue;
+	}
+	/**
+	* The type for options and arguments of `dotnet pack`. See https://learn.microsoft.com/en-us/dotnet/core/tools/dotnet-pack.
+	*
+	* {@link NRI.PackPackagesOptionsType.t.propertyOverrides `propertyOverrides`}
+	* is a wrapper for MSBuild's `-property:<n>=<v>` properties override arg.
+	*/
+	static PackPackagesOptionsType = Object.freeze(type({
+		"propertyOverrides?": type("Record<string,string>"),
+		"artifactsPath?": "string",
+		"configuration?": "\"Release\" | \"Debug\"",
+		"disableBuildServers?": "boolean",
+		"force?": "boolean",
+		"includeSource?": "boolean",
+		"includeSymbols?": "boolean",
+		"interactive?": "boolean",
+		"noBuild?": "boolean",
+		"noLogo?": "boolean",
+		"noRestore?": "boolean",
+		"output?": "string",
+		"runtime?": "string",
+		"serviceable?": "boolean",
+		"terminalLogger?": "\"auto\" | \"on\" | \"off\"",
+		"useCurrentRuntime?": "boolean",
+		"verbosity?": "\"quiet\" | \"minimal\" | \"normal\" | \"detailed\" | \"diagnostic\"",
+		"versionSuffix?": "string",
+		"-GetItem?": type.string.array().readonly().or("string[]")
+	}));
+	static PackDummyPackagesOptionsType = this.PackPackagesOptionsType.omit("output");
+	/**
+	* Get a `dotnet pack` command line string, outputting the package(s) to a
+	* path determined by this method's parameters.
+	* When pushing the package(s), you only need to supply the main .nupkg's path
+	* or its directory to the dotnet CLI—by default, it will also push the
+	* symbols package, if present.
+	* @param opts Options passed to
+	* `dotnet pack`, excluding the required `<PROJECT | SOLUTION>` argument. The
+	* {@link PackPackagesOptionsType.t.output} path is modified according to the
+	* {@link usePerSourceSubfolder} and {@link usePerPackageIdSubfolder}
+	* arguments.
+	* @param usePerSourceSubfolder If true, the path of the package output will
+	* include a subfolder named after the NuGet Source.
+	* @param usePerPackageIdSubfolder If true, the path of the package output
+	* will include a subfolder named after the NuGet package's ID.
+	* @returns `dotnet pack "${this.project.Properties.MSBuildProjectFullPath}"
+	* -o "${outDir}"` where outDir may be `${cwd()}/publish/${NugetRegistryInfo.GetNameForURL(this.source)}/${this._project.Properties.PackageId}`
+	*/
+	GetPackCommand(opts, usePerSourceSubfolder = false, usePerPackageIdSubfolder = false) {
+		const validOpts = NRI.PackPackagesOptionsType.from(opts);
+		type.boolean.assert(usePerSourceSubfolder);
+		type.boolean.assert(usePerPackageIdSubfolder);
+		validOpts.output ??= node_path.join(cwd(), "publish");
+		if (usePerSourceSubfolder) validOpts.output = node_path.join(validOpts.output, NugetRegistryInfo.GetDirNameForSource(this.source), node_path.sep);
+		if (usePerPackageIdSubfolder) validOpts.output = node_path.join(validOpts.output, this._project.Properties.PackageId, node_path.sep);
+		const packCmdArr = [
+			"dotnet",
+			"pack",
+			`"${this._project.Properties.MSBuildProjectFullPath}"`
+		];
+		if (validOpts.artifactsPath !== void 0) packCmdArr.push("--artifactsPath", `"${validOpts.artifactsPath}"`);
+		if (validOpts.configuration !== void 0) packCmdArr.push("--configuration", validOpts.configuration);
+		if (validOpts.disableBuildServers === true) packCmdArr.push("--disable-build-servers");
+		if (validOpts.force === true) packCmdArr.push("--force");
+		if (validOpts.includeSource === true) packCmdArr.push("--include-source");
+		if (validOpts.includeSymbols === true) packCmdArr.push("--include-symbols");
+		if (validOpts.interactive === true) packCmdArr.push("--interactive");
+		if (validOpts.noBuild === true) packCmdArr.push("--no-build");
+		if (validOpts.noLogo === true) packCmdArr.push("--nologo");
+		if (validOpts.noRestore === true) packCmdArr.push("--no-restore");
+		if (validOpts.runtime !== void 0) packCmdArr.push("--runtime", validOpts.runtime);
+		if (validOpts.serviceable === true) packCmdArr.push("--serviceable");
+		if (validOpts.terminalLogger !== void 0) packCmdArr.push("--tl", validOpts.terminalLogger);
+		if (validOpts.useCurrentRuntime === true) packCmdArr.push("--use-current-runtime");
+		if (validOpts.verbosity !== void 0) packCmdArr.push("--verbosity", validOpts.verbosity);
+		if (validOpts.versionSuffix !== void 0) packCmdArr.push("--version-suffix", validOpts.versionSuffix);
+		/**
+		* Haphazard. I need to override the Version and I'm not considering side
+		* effects of arbitrary overrides.
+		*/
+		if (validOpts.propertyOverrides) {
+			/** convert propertyOverrides record to "-p:n0=v0;n1=v1;n2=v2" et cetera */
+			const assignments = "-p:" + Object.entries(validOpts.propertyOverrides).map((v) => `${v[0]}=${v[1]}`).join(";");
+			packCmdArr.push(`"${assignments}"`);
+		}
+		if (validOpts["-GetItem"] && validOpts["-GetItem"].length > 0) packCmdArr.push(`-GetItem:${validOpts["-GetItem"].join(",")}`);
+		packCmdArr.push("-o", `"${validOpts.output}"`);
+		return packCmdArr.join(" ");
+	}
+	/**
+	* !Not ready for use! Remove private modifier and commit as `feat(dotnet)` when ready for release!
+	* Blocking Issue: convert all dotnet-related functionality to a Semantic Release plugin!
+	* The current {@link _srcd SemanticReleaseConfigDotnet} leverages
+	* `@semantic-release/exec` to invoke dotnet commands. This is fine for
+	* relatively short command lines, but chaining commands with ' && ' results
+	* in quickly-growing complexity.
+	* NuGet packages should be created during the `prepare` step, but complex
+	* configuration of `dotnet pack` via command lines intended to be invoked by
+	* `@semantic-release/exec` is impractical.
+	* @param opts `dotnet pack` options. See `dotnet pack -h`,
+	* https://learn.microsoft.com/en-us/dotnet/core/tools/dotnet-pack, and
+	* {@link PackPackagesOptionsType}.
+	* {@link opts['-GetItem']} will _always_ have '_OutputPackItems'.
+	* @param [usePerSourceSubfolder] If `true`, modify the output path to
+	* include a subfolder bearing a path-safe encoding of the NuGet Source that
+	* will receive the nupkg.
+	* @param [usePerPackageIdSubfolder] If `true`, modify the output path
+	* to include a subfolder named after the the PackageId.
+	* @returns a string[] containing the full file paths of all new packages i.e.
+	* .nupkg, .symbols.nupkg, .snupkg
+	*/
+	async _PackPackages(opts, usePerSourceSubfolder = false, usePerPackageIdSubfolder = false) {
+		opts["-GetItem"] = [...opts["-GetItem"] ?? [], key_OutputPackItems];
+		const packCmd = this.GetPackCommand(opts, usePerSourceSubfolder, usePerPackageIdSubfolder);
+		let packOutput = void 0;
+		while (packOutput === void 0) packOutput = await setTimeout(1e3, execAsync(packCmd, true)).then(async (p) => await p).catch(catchEBUSY);
+		return new MSBuildEvaluationOutput(packOutput.stdout).Items?.[key_OutputPackItems]?.filter((item) => item.Extension !== ".nuspec").map((item) => item.FullPath) ?? [];
+	}
+	/**
+	* Create a dummy package for the current {@link project} by executing a
+	* command line like \``dotnet pack ${this.project.Properties.MSBuildProjectFullPath} -p:Version=0.0.1-DUMMY -output ${getDummiesDir(this._project)}/${GetNameForURL(this.source)}`\`
+	* @param opts Options passed to
+	* `dotnet pack`, excluding the required `<PROJECT | SOLUTION>` argument.
+	* - The `output` field is ignored and overwritten. It is replaced with
+	*   ${{@link getDummiesDir}({@link project})}/${{@link GetDirNameForSource}({@link source})}
+	* - The `output` path will be affixed with a folder named after this
+	* {@link NugetRegistryInfo#source}, but will not include a subfolder for the
+	* {@link NugetRegistryInfo#project NugetRegistryInfo.project}.{@link MSBuildProject#Properties Properties}.{@link MSBuildProject#Properties#PackageId PackageId}.
+	* @returns the full paths of all nupkg, symbols.nupkg, and snupkg files
+	* created by the Pack target, as extracted from the dotnet process's STDOUT.
+	* If mixed with other nupkgs, filter for the {@link NugetProjectProperties#PackageId}
+	*/
+	async PackDummyPackage(opts) {
+		const packCmd = this.GetPackCommand({
+			...opts,
+			output: getDummiesDir(this._project),
+			propertyOverrides: {
+				...opts.propertyOverrides,
+				Version: "0.0.1-DUMMY",
+				UpdateVersionProperties: "false"
+			},
+			"-GetItem": [...opts["-GetItem"] ?? [], key_OutputPackItems]
+		}, true);
+		let packOutput = void 0;
+		while (packOutput === void 0) packOutput = await setTimeout(1e3, execAsync(packCmd, true)).then(async (p) => await p).catch(catchEBUSY);
+		return new MSBuildEvaluationOutput(packOutput.stdout).Items?.[key_OutputPackItems]?.filter((item) => item.Extension !== ".nuspec").map((item) => item.FullPath) ?? [];
+	}
+	/**
+	* Also includes required argument 'ROOT': the directory in which packages
+	* should be present and ready to be pushed the default or specified Source.
+	* The ROOT may also include wildcards e.g. `*.nupkg`, `**\\*.nupkg`
+	* See https://learn.microsoft.com/en-us/dotnet/core/tools/dotnet-nuget-push
+	*
+	* Specific to this API:
+	* If you want to use this API's default root value (\`${cwd()}/publish`), assign an empty string.
+	*/
+	static PushPackagesOptionsType = Object.freeze(type({
+		root: "string",
+		"apiKey?": "string",
+		"configFile?": "string",
+		"disableBuffering?": "boolean",
+		"forceEnglishOutput?": "boolean",
+		"interactive?": "boolean",
+		"noServiceEndpoint?": "boolean",
+		"noSymbols?": "boolean",
+		"skipDuplicate?": "boolean",
+		"source?": "string",
+		"symbolApiKey?": "string",
+		"symbolSource?": "string",
+		"timeout?": "number"
+	}));
+	/**
+	* {@link NRI.PushPackagesOptionsType} sans {@link NRI.PushPackagesOptionsType.t.root}.
+	* The result of {@link getDummiesDir} is used, instead.
+	*/
+	static PushDummyPackagesOptionsType = NugetRegistryInfo.PushPackagesOptionsType.merge({ skipDuplicate: "true = true" }).omit("root");
+	/**
+	* Create a `dotnet nuget push` command line from the given options and
+	* optional boolean parameters.
+	* @param opts See {@link PushPackagesOptionsType}
+	* @param usePerSourceSubfolder If `true`, the NuGet Source name or URL is formatted
+	* to a folder name and appended to the ROOT as a subfolder. Do not use
+	* wildcards in ROOT with this set to `true`!
+	* @param usePerPackageIdSubfolder  If `true`, the
+	* {@link project}'s {@link NugetProjectProperties#PackageId}
+	* is appended to the ROOT as a subfolder. Do not use wildcards in
+	* ROOT with this set to `true`!
+	* @returns A `dotnet nuget push` command line formatted with the
+	* appropriate arguments.
+	*/
+	GetPushCommand(opts, usePerSourceSubfolder = false, usePerPackageIdSubfolder = false) {
+		const validOpts = NRI.PushPackagesOptionsType.from(opts);
+		type.boolean.assert(usePerSourceSubfolder);
+		type.boolean.assert(usePerPackageIdSubfolder);
+		validOpts.root = validOpts.root === "" ? `${cwd()}/publish` : validOpts.root;
+		if (usePerSourceSubfolder) validOpts.root = node_path.join(validOpts.root, NugetRegistryInfo.GetDirNameForSource(this.source), node_path.sep);
+		if (usePerPackageIdSubfolder) validOpts.root = node_path.join(validOpts.root, this._project.Properties.PackageId, node_path.sep);
+		const packCmdArr = [
+			"dotnet",
+			"nuget",
+			"push",
+			`"${node_path.join(validOpts.root, "*.nupkg")}"`
+		];
+		if (this.resolvedEnvVariable) validOpts.apiKey ??= NRI._GetTokenValue(this.resolvedEnvVariable);
+		/**
+		* If apiKey is an empty string, defer to the dotnet CLI's NuGet client
+		* ability to lookup API keys saved via `dotnet nuget add source` or NuGet config
+		* files.
+		*/
+		if (validOpts.apiKey && validOpts.apiKey !== "") packCmdArr.push("--api-key", validOpts.apiKey);
+		if (validOpts.configFile) packCmdArr.push("--configfile", validOpts.configFile);
+		if (validOpts.disableBuffering === true) packCmdArr.push("--disable-buffering");
+		if (validOpts.forceEnglishOutput === true) packCmdArr.push("--force-english-output");
+		if (validOpts.interactive === true) packCmdArr.push("--interactive");
+		if (validOpts.noServiceEndpoint === true) packCmdArr.push("--no-service-endpoint");
+		if (validOpts.noSymbols === true) packCmdArr.push("--no-symbols");
+		if (validOpts.skipDuplicate === true) packCmdArr.push("--skip-duplicate");
+		validOpts.source ??= this.source;
+		packCmdArr.push("--source", validOpts.source);
+		if (validOpts.symbolApiKey !== void 0) packCmdArr.push("--symbol-api-key", validOpts.symbolApiKey);
+		if (validOpts.symbolSource !== void 0) packCmdArr.push("--symbol-source", validOpts.symbolSource);
+		if (validOpts.timeout !== void 0) packCmdArr.push("--timeout", validOpts.timeout.toString());
+		return packCmdArr.join(" ");
+	}
+	/**
+	* Immediately push packages. The input path may be modified according to the
+	* {@link usePerSourceSubfolder} and {@link usePerPackageIdSubfolder}
+	* arguments.
+	* @param opts The `dotnet nuget push` command line options, including the
+	* ROOT argument, the directory containing local nuget packages ready to be
+	* pushed.
+	* @param usePerSourceSubfolder If `true`, the NuGet Source name or URL is formatted
+	* to a folder name and appended to the ROOT as a subfolder. Do not use
+	* wildcards in ROOT with this set to `true`!
+	* @param usePerPackageIdSubfolder If `true`, the current {@link project}'s
+	* PackageId is appended to the ROOT as a subfolder. Do not use wildcards in
+	* ROOT with this set to `true`!
+	*/
+	async _PushPackages(opts, usePerSourceSubfolder = false, usePerPackageIdSubfolder = false) {
+		await execAsync(this.GetPushCommand(opts, usePerSourceSubfolder, usePerPackageIdSubfolder), true).catch((error) => {
+			const _error = isError(error) ? error : new Error(JSON.stringify(error));
+			throw opts.apiKey ? _censorTokenInError(_error, opts.apiKey) : _error;
+		});
+	}
+	/**
+	*
+	* Get a `dotnet nuget push` command for pushing one or more nupkg/snupkg
+	* files created by {@link GetPackCommand} or {@link _PackPackages}.\
+	* Like {@link PackDummyPackage}, the output/ROOT path will include a
+	* folder named after this NRI instance's {@link NugetRegistryInfo#source},
+	* but will not include a subfolder for the
+	* {@link NugetRegistryInfo#project NugetRegistryInfo.project}.{@link MSBuildProject#Properties Properties}.{@link MSBuildProject#Properties#PackageId PackageId}
+	* @example
+	* ```ts
+	* const packAndPushDummyCmd = [
+	*   nri.GetPackCommand(
+	*     NugetRegistryInfo.PackPackagesOptionsType.from({ root: '' }),
+	*     false,
+	*     false,
+	*   ),
+	*   nri.GetPushDummyPackageCommand(pushOpts, false, false),
+	* ].join(' && ')
+	* ```
+	* @param opts options for `dotnet nuget push`. The following
+	* fields are overwritten:
+	* - root: getDummiesDir(this.project)
+	* - skipDuplicates: true
+	* @returns a `dotnet nuget push` command to push a dummy package
+	* (created by executing {@link PackDummyPackage}) to {@link source}
+	*/
+	GetPushDummyCommand(opts) {
+		return this.GetPushCommand({
+			...NRI.PushDummyPackagesOptionsType.from(opts),
+			root: getDummiesDir(this._project)
+		}, true);
+	}
+	/**
+	* Call {@link GetPushDummyCommand} and immediately execute it.
+	* @throws {Error} when the process exits with an error code indicating
+	* failure i.e. the command line is invalid, the process fails to start,
+	* the push fails, et cetera.
+	* @param opts the ROOT arg and options for `dotnet nuget push`. The following
+	* fields are overwritten:
+	* - root: getDummiesDir(this.project)
+	* - skipDuplicates: true
+	* @returns The return type of {@link execAsync} i.e. a {@link Promise} resolving to `{ stdout: string; stderr: string }`.
+	*/
+	async _PushDummyPackages(opts) {
+		return await execAsync(this.GetPushDummyCommand(opts), true).catch((error) => {
+			const _error = isError(error) ? error : new Error(String(error));
+			throw opts.apiKey ? _censorTokenInError(_error, opts.apiKey) : _error;
+		});
+	}
+	static _NugetSearchReturnTypes = { ExactMatch: { v2: type({
+		version: "2",
+		problems: "unknown[]",
+		searchResult: [{
+			sourceName: "string",
+			packages: type({
+				id: "string",
+				version: type.keywords.string.semver
+			}).array()
+		}]
+	}) } };
+	static _ParseNugetSearchReturn = type("string.json.parse").to(this._NugetSearchReturnTypes.ExactMatch.v2);
+	/**
+	* !WARNING: this method requires the Nuget Source to be configured via `dotnet nuget add source` or `dotnet nuget update source`. `NUGET_TOKEN` works, but it may be vulnerable to supply chain attacks.\
+	* Call during the `prepare` step of a Semantic Release run.\
+	* Determine if the `nextVersion` generated during the `analyze` Semantic
+	* Release step was already published to the NuGet {@link source}.
+	* @param source The name or URI of the NuGet Source to search. If this API
+	* endpoint does not support searches, the operation will fail. If this API
+	* endpoint requires authentication (e.g. GitHub), it must be configured via
+	* `dotnet nuget add source` or `dotnet nuget update source` before calling
+	* this method.
+	* @param packageId The ID of the NuGet package to search for.
+	* @param nextVersion The nextVersion value generated by semantic-release's hidden ["Create Git tag" step](https://semantic-release.gitbook.io/semantic-release#:~:text=the%20last%20release.-,Create%20Git%20tag,-Create%20a%20Git).
+	* @returns A promised boolean.
+	* If the promise resolves to `true`, the semantic release run should be
+	* cancelled immediately.
+	* Otherwise, the release should proceed.
+	* @todo utilize in custom plugin inserted at the beginning of `prepare`
+	*/
+	static async IsNextVersionAlreadyPublished(source, packageId, nextVersion) {
+		if (nextVersion === "") throw new Error("The value of nextVersion is empty");
+		return await execAsync(`dotnet package search --format JSON --exact-match --source ${source} --prerelease ${packageId}`, true).then((stdPair) => stdPair.stdout).then((json) => this._ParseNugetSearchReturn(json)).then((errsOrObj) => errsOrObj instanceof type.errors ? errsOrObj.throw() : errsOrObj).then((obj) => obj.searchResult).then((results) => results[0].packages).then((pkgs) => pkgs.find((p) => p.version === type("string.semver").from(nextVersion))).then((pkg) => pkg !== void 0);
+	}
+	/**
+	* !WARNING: GITHUB_OUTPUT must be the full path to an environment file.
+	* The plugin "semantic-release-output-variables" next-release-version
+	*
+	* !WARNING: NuGet Source API Key mus tbe configured via `dotnet nuget add source` or `dotnet nuget update source`.
+	* Some Sources (e.g. GitHub) require authentication for package searches.
+	*
+	* # Authenticating NuGet Package Searches
+	*
+	* ## GitHub NuGet Registry authentication
+	* - {@link https://docs.github.com/en/packages/working-with-a-github-packages-registry/working-with-the-nuget-registry#authenticating-in-a-github-actions-workflow Authenticating in a GitHub Actions workflow}
+	* - {@link https://docs.github.com/en/packages/working-with-a-github-packages-registry/working-with-the-nuget-registry#authenticating-with-a-personal-access-token Authenticating with a personal access token}.
+	* ## For GitLab NuGet Registry authentication, see
+	* - {@link https://docs.gitlab.com/ee/user/packages/nuget_repository/#add-a-source-with-the-net-cli Add a source with the .NET CLI}
+	* @returns a string containing a Node.JS command line invoking {@link ./IsNextVersionAlreadyPublished.cli.ts}
+	* @see {@link ./IsNextVersionAlreadyPublished.cli.ts}, {@link ./IsNextVersionAlreadyPublished.cli.js}
+	*/
+	GetIsNextVersionAlreadyPublishedCommand() {
+		getGithubOutputSync();
+		return `node ${node_path.join(import.meta.dirname, "./IsNextVersionAlreadyPublished.cli.js")} --packageId ${this._project.Properties.PackageId} --source ${this.source}`;
+	}
+};
+const NRI = NugetRegistryInfo;
+/**
+* The base type for {@link NRIOpts} and related types. Extend this type while
+* overriding member types via {@link NRIOptsBase.merge}
+*/
+const NRIOptsBase = type({
+	project: type.instanceOf(MSBuildProject).or(type.instanceOf(MSBuildProject).readonly()),
+	source: type.string,
+	tokenEnvVars: type.string.array().readonly()
+});
+/**
+* The type of the parameter for {@link NugetRegistryInfo}'s constructor.
+*/
+const NRIOpts = NRIOptsBase.merge({
+	tokenEnvVars: NRIOptsBase.get("tokenEnvVars").default(() => NugetRegistryInfo.DefaultTokenEnvVars),
+	source: NRIOptsBase.get("source").default(() => defaultNugetSource)
+});
+/**
+* Replace all occurrences of {@link token} in the {@link string} with '***'.
+* @param string The string in which a {@link token} may be found.
+* @param token The NuGet API token you definitely don't want to leak!
+* @returns A modified copy of the {@link string} with all occurrences of the
+* {@link token} replaced with '***'.
+*/
+function _censorToken(string, token) {
+	return string.replaceAll(token, "***");
+}
+/**
+* Censor all occurrences of an API {@link token} in an {@link error}.
+* @param error A {@link ExecException} in which the NuGet API {@link token} may be found.
+* @param token The value of the NuGet API token
+* @returns A modified copy of the provided exception sans any occurrence of the
+* NuGet API token.
+*/
+function _censorTokenInError(error, token) {
+	return Object.assign(error, JSON.parse(_censorToken(JSON.stringify({
+		...error,
+		message: error.message,
+		stack: error.stack
+	}), token)));
+}
+//#endregion
+export { NRIOpts, NRIOptsBase, NugetRegistryInfo, getGithubOutput, getGithubOutputSync };
+
 //# sourceMappingURL=NugetRegistryInfo.mjs.map