@halospv3/hce.shared-config 2.2.3 → 2.3.0

package/src/dotnet/dotnetGHPR.ts

@@ -0,0 +1,76 @@
+import type { NuGetRegistryInfo } from './dotnetHelpers.js';
+
+// todo: support custom base URL for private GitHub instances
+async function tokenCanWritePackages(tokenEnvVar: string) {
+	const tokenValue = process.env[tokenEnvVar];
+	if (tokenValue === undefined)
+		throw new TypeError(`The environment variable ${tokenEnvVar} is undefined!`)
+	const reqH = { authorization: `token ${tokenValue}` };
+	// CJS compatibility - import { request } from '@octokit/request
+	const request = (await import('@octokit/request')).request;
+	const response = await request('GET /', { headers: reqH });
+	const scopes = response.headers['x-oauth-scopes'];
+	if (scopes) {
+		return scopes.includes('write:packages') || scopes.includes('write:packages');
+	}
+	return false;
+}
+
+const { GITHUB_REPOSITORY_OWNER } = process.env;
+
+export const nugetGitHubUrlBase = 'https://nuget.pkg.github.com';
+export const nugetGitHubUrl = GITHUB_REPOSITORY_OWNER
+	? `${nugetGitHubUrlBase}/${GITHUB_REPOSITORY_OWNER}/index.json`
+	: undefined;
+
+/**
+ * Get a {@link NuGetRegistryInfo} for pushing to your GitHub Packages NuGet registry.
+ * todo: add support for private, custom GitHub instances. Token is only validated against github.com.
+ * @export
+ * @param {string} [tokenEnvVar="GITHUB_TOKEN"] The name of environment variable storing the GitHub Packages NuGet registry API key. Defaults to `"GITHUB_TOKEN"`;
+ * @param {string} [url=tokenEnvVar] The url of the GitHub Packages NuGet registry. Defaults to {@link nugetGitHubUrl}.
+ * @returns {(NuGetRegistryInfo | undefined)} a {@link NuGetRegistryInfo} object if {@link tokenEnvVar} and {@link url} are defined. Else, `undefined`.
+ * note: `url` defaults to job's repository owner's GitHub registry in GitHub Actions workflow. If GITHUB_REPOSITORY_OWNER is not defined, then an error will be logged and `undefined` will be returned.
+ */
+export async function getGithubNugetRegistryPair(
+	tokenEnvVar = 'GITHUB_TOKEN',
+	url: string | undefined = nugetGitHubUrl,
+): Promise<NuGetRegistryInfo | undefined> {
+	// yes, this is stupid. No, I won't change it.
+	const isTokenDefined = process.env[tokenEnvVar] !== undefined;
+	const isUrlDefined = url !== undefined;
+	const canTokenWritePackages = isTokenDefined ? await tokenCanWritePackages(tokenEnvVar) : false;
+
+	const errors: Error[] = [];
+
+	if (!isTokenDefined)
+		errors.push(
+			new Error(
+				`The environment variable ${tokenEnvVar} was specified as the source of the token to push a NuGet package to GitHub, but the environment variable does not exist.`,
+			),
+		);
+	if (!isUrlDefined) {
+		errors.push(
+			new Error(
+				'The url for the GitHub Packages NuGet registry was undefined.\n' +
+				'If running in a GitHub Actions workflow, something is seriously wrong.\n' +
+				'If running in a different CI/CD pipeline and you wish to cross-push to GHPR, ensure GITHUB_REPOSITORY_OWNER is set correctly.\n',
+			),
+		);
+	}
+	if (!canTokenWritePackages) {
+		// yes, this is a critical error that should be fixed before Semantic Release can succeed.
+		// yes, this is incredibly irritating to deal with in local runs.
+		errors.push(
+			new Error(
+				'The provided GitHub token has insufficient permissions or is a fine-grained permissions token. Only class Personal Access Tokens (classic) or workflow tokens with `repo` or `write:packages` permission can push a package.',
+			),
+		);
+	}
+
+	// conditions checked so `url` is certainly defined
+	if (isTokenDefined && isUrlDefined && canTokenWritePackages)
+		return { tokenEnvVar, url };
+
+	throw new Error(`One more more errors occurred when getting GHPR url-token pair. Errors:\n${errors.map(v => v.message).join('\n')}`);
+}

package/src/dotnet/dotnetGLPR.ts

@@ -0,0 +1,46 @@
+import { error } from 'node:console';
+import type { NuGetRegistryInfo } from './dotnetHelpers.js';
+
+const { CI_API_V4_URL, CI_PROJECT_ID } = process.env;
+const nameof = {
+	CI_API_V4_URL: 'CI_API_V4_URL',
+	CI_PROJECT_ID: 'CI_PROJECT_ID',
+};
+
+export const GitLabTokenEnvVar = 'CI_JOB_TOKEN';
+export const nugetGitLabUrlBase = CI_API_V4_URL;
+export const nugetGitLabUrl: string | undefined =
+	CI_API_V4_URL && CI_PROJECT_ID
+		? `${CI_API_V4_URL}/projects/${CI_PROJECT_ID}/packages/nuget/index.json`
+		: undefined;
+
+/**
+ * Get a {@link NuGetRegistryInfo} for pushing to your GitLab Packages NuGet registry.
+ * @export
+ * @param {string} [tokenEnvVar=GitLabTokenEnvVar] The name of environment variable storing the GitLab Packages NuGet registry API key. Defaults to {@link GitLabTokenEnvVar}.
+ * @param {string} [url=nugetGitLabUrl] The url of the GitLab Packages NuGet registry. Defaults to {@link nugetGitLabUrl}.
+ * @returns {(NuGetRegistryInfo | undefined)} a {@link NuGetRegistryInfo} object if {@link tokenEnvVar} and {@link url} are defined. Else, undefined.
+ */
+export function getGitlabNugetRegistryPair(
+	tokenEnvVar: string = GitLabTokenEnvVar,
+	url: string | undefined = nugetGitLabUrl,
+): NuGetRegistryInfo | undefined {
+	// yes, this is stupid. No, I won't change it.
+	if (!process.env[tokenEnvVar]) {
+		error(
+			new Error(
+				`The environment variable ${tokenEnvVar} was specified as the source of the token to push a NuGet package to GitLab, but the environment variable does not exist.`,
+			),
+		);
+		return undefined;
+	}
+	if (url) {
+		return { tokenEnvVar, url };
+	}
+	error(
+		new Error(
+			`The environment variables ${nameof.CI_API_V4_URL} or ${nameof.CI_PROJECT_ID} do not exist and a custom GitLab Packages NuGet registry URL was not provided.`,
+		),
+	);
+	return undefined;
+}

package/src/dotnet/dotnetHelpers.ts

@@ -0,0 +1,182 @@
+import { ok } from 'node:assert/strict';
+import { getGithubNugetRegistryPair, nugetGitHubUrlBase } from './dotnetGHPR.js';
+import { getGitlabNugetRegistryPair } from './dotnetGLPR.js';
+import { MSBuildProject, MSBuildProjectPreDefinedProperties } from './MSBuildProject.js';
+
+/**
+ * Build a prepareCmd string from .NET project paths and `dotnet nuget sign` arguments.
+ *
+ * todo: parse Solution files to publish all projects with default Publish parameters (as evaluated by MSBuild). If multi-targeting frameworks and/or runtime, evaluate those properties for Publish permutation matrix.
+ * todo: cleanup, docs
+ * @export
+ * @param {string[]} projectsToPublish
+ * @param {string[]} projectsToPackAndPush Relative and/or full file paths of projects to pass to `dotnet pack`. By default, these will be output to `./publish/`.
+ * @param {string[]} dotnetNugetSignArgs Arguments appended to `dotnet nuget sign`. You can also append '&&' if you want to start a new command or if you want to sign different sets of packages with different keys.
+ */
+export function configurePrepareCmd(
+	projectsToPublish: string[],
+	projectsToPackAndPush: string[],
+	dotnetNugetSignArgs: string[] = ['./publish'],
+) {
+	// These are later evaluated with MSBuild, but are passed via --framework and --runtime arguments instead of -p:TargetFramework
+	const publishProperties = MSBuildProjectPreDefinedProperties;
+
+	function formatDotnetPublish(): string {
+		/* Fun Fact: You can define a property and get the evaluated value in the same command!
+		```pwsh
+		dotnet msbuild .\src\HXE.csproj -property:RuntimeIdentifiers="""place;holder""" -getProperty:RuntimeIdentifiers
+		place;holder
+		```
+			enclosing with """ is required in pwsh to prevent the semicolon from breaking the string.
+		*/
+		let dotnetPublishArgs: string[][];
+		if (Array.isArray(projectsToPublish) && projectsToPublish.length > 0) {
+			// each may have TargetFramework OR TargetFrameworks (plural)
+			const evaluatedProjects: MSBuildProject[] = projectsToPublish.map(
+				(proj) => new MSBuildProject(proj, publishProperties),
+			);
+			// args appended to "dotnet publish", joined by space
+			dotnetPublishArgs = evaluatedProjects.flatMap((proj) => {
+				const args: string[] = [proj.Properties.FullPath];
+
+				function appendCustomProperties() {
+					// convert to dictionary and filter for user-defined properties.
+					const dictionary = Object.entries(proj.Properties).filter(
+						(p) => !publishProperties.includes(p[0]),
+					);
+					if (dictionary.length > 0) {
+						/* format remaining properties as "-p:Property=Value" and append to args */
+						args.push(
+							...dictionary.map((keyValuePair) => `-p:${keyValuePair[0]}=${keyValuePair[1]}`),
+						);
+					}
+				}
+				appendCustomProperties();
+
+				const cmdPermutations: string[][] = []; // forEach, run dotnet [...args,...v]
+
+				function formatFrameworksAndRuntimes() {
+					const RIDs: string[] =
+						proj.Properties.RuntimeIdentifiers.length > 0
+							? proj.Properties.RuntimeIdentifiers.split(';')
+							: [];
+					const TFMs: string[] =
+						proj.Properties.TargetFrameworks.length > 0
+							? proj.Properties.TargetFrameworks.split(';')
+							: [];
+					if (RIDs.length > 0) {
+						if (TFMs.length > 0) {
+							for (const RID of RIDs) {
+								for (const TFM of TFMs) {
+									cmdPermutations.push(['--runtime', RID, '--framework', TFM]);
+								}
+							}
+						} else {
+							// assume singular TFM. No need to specify it.
+							for (const RID of RIDs) {
+								cmdPermutations.push(['--runtime', RID]);
+							}
+						}
+					} else if (TFMs.length > 0) {
+						for (const TFM of TFMs) {
+							cmdPermutations.push(['--framework', TFM]);
+						}
+					}
+				}
+				formatFrameworksAndRuntimes();
+
+				return cmdPermutations.length > 0
+					? cmdPermutations.map((permArgs) => [...args, ...permArgs]) // string[][]
+					: [args]; // string[][]
+			}); // string[][][] -> string[][]
+		} else
+			throw new Error(
+				`Type of projectsToPublish (${typeof projectsToPublish}) is not allowed. Expected a string[] where length > 0.`,
+			);
+
+		return dotnetPublishArgs.map((args) => `dotnet publish ${args.join(' ')}`).join(' && ');
+	}
+
+	function formatDotnetPack(): string {
+		return projectsToPackAndPush.map((v) => `dotnet pack ${v}`).join(' && ');
+	}
+
+	function formatDotnetNugetSign(): string {
+		switch (dotnetNugetSignArgs.length) {
+			case 0:
+				return '';
+			default:
+				return `dotnet nuget sign ${dotnetNugetSignArgs.join(' ')}`;
+			// default: {
+			//     throw new Error("")
+			//     // this needs a rework.
+			//     const packagePaths: string[] = [];
+			//     dotnetNugetSignArgs.forEach((dotnetNugetSignArg, i) => {
+			//         // if current arg doesn't start with '-' and (current arg is first -OR- previous arg also does not start with '-')...
+			//         if (!dotnetNugetSignArg.startsWith("-") && (i === 0 || (i > 0 && !dotnetNugetSignArgs[i - 1].startsWith("-")))) {
+			//             // ...then it's probably a package path.
+			//             packagePaths.push(dotnetNugetSignArg);
+			//         }
+			//     });
+			//     if (packagePaths.length === 0)
+			//         return `dotnet nuget sign ${dotnetNugetSignArgs.join(" ")}`
+			//     else return
+			// }
+		}
+	}
+
+	const dotnetPublish = formatDotnetPublish();
+	const dotnetPack = formatDotnetPack();
+	const dotnetNugetSign = formatDotnetNugetSign();
+	return [dotnetPublish, dotnetPack, dotnetNugetSign].join(' && ');
+}
+
+export interface NuGetRegistryInfo {
+	tokenEnvVar: string;
+	url: string;
+	user?: string | undefined;
+}
+export const nugetDefault: NuGetRegistryInfo = {
+	tokenEnvVar: 'NUGET_TOKEN',
+	url: 'https://api.nuget.org/v3/index.json',
+};
+
+/**
+ * todo
+ * @param nupkgDir
+ * @param registries
+ * @param pushToGitHub
+ * @returns
+ */
+export async function configureDotnetNugetPush(
+	nupkgDir = './publish',
+	registries: NuGetRegistryInfo[] = [nugetDefault],
+	pushToGitHub = true,
+) {
+	if (registries.some((registry) => registry.url.trim() === ''))
+		throw new Error('The URL for one of the provided NuGet registries was empty or whitespace.');
+
+	// if user did not specify a GitHub NuGet Registry, try determine default values and add the Source.
+	if (pushToGitHub && !registries.some((reg) => reg.url.startsWith(nugetGitHubUrlBase))) {
+		const ghPair = await getGithubNugetRegistryPair();
+		if (ghPair) {
+			registries.push(ghPair);
+		}
+	}
+	if (!registries.some((reg) => reg.url.startsWith(nugetGitHubUrlBase))) {
+		const glPair = getGitlabNugetRegistryPair();
+		if (glPair) {
+			registries.push(glPair);
+		}
+	}
+
+	return registries
+		.map(
+			(registry) => {
+				const tokenValue = process.env[registry.tokenEnvVar];
+				ok(tokenValue, `The environment variable ${registry.tokenEnvVar} is undefined!`);
+				`dotnet nuget push ${nupkgDir} --source ${registry.url} --token ${tokenValue}`
+			}
+		)
+		.join(' && ');
+}

package/src/dotnet.ts

@@ -0,0 +1,5 @@
+export * as dotnetGHPR from "./dotnet/dotnetGHPR.js"
+export * as dotnetGLPR from "./dotnet/dotnetGLPR.js"
+export * as dotnetHelpers from "./dotnet/dotnetHelpers.js"
+export * as msbuildProject from "./dotnet/MSBuildProject.js"
+export * as msbuildProjectProperties from "./dotnet/MSBuildProjectProperties.js"

package/src/eslintConfig.ts

@@ -0,0 +1,86 @@
+import jsonc from "eslint-plugin-jsonc";
+import tseslint from "typescript-eslint";
+import { type TSESLint } from "@typescript-eslint/utils";
+import eslint from "@eslint/js";
+import globals from "globals" with {type: "json"};
+
+// https://eslint.org/docs/latest/use/configure/migration-guide#using-eslintrc-configs-in-flat-config
+// https://www.google.com/search?q=javascript+recurse+through+object+and+remove+undefined+properties
+
+const globalIgnores: TSESLint.FlatConfig.Config = {
+    name: "global ignores",
+    ignores: [
+        "_tsout/**/*",
+        "_tsout/*",
+        "_tsout/",
+        "cjs/**/*",
+        "cjs/*/*",
+        "cjs/*",
+        "mjs/**/*",
+        "mjs/*",
+        "mjs/",
+        "node_modules/**/*",
+        "**/node_modules/**/*"
+    ]
+};
+
+export default tseslint.config(
+    {
+        name: "flat/recommended-with-json - https://github.com/ota-meshi/eslint-plugin-jsonc",
+        extends: jsonc.configs["flat/recommended-with-json"],
+        files: [
+            "*.json",
+            "**/*.json"
+        ],
+        ignores: globalIgnores.ignores
+    },
+    {
+        name: "flat/recommended-with-json5 - https://github.com/ota-meshi/eslint-plugin-jsonc",
+        extends: jsonc.configs["flat/recommended-with-json5"],
+        files: [
+            "*.json5",
+            "**/*.json5"
+        ],
+        ignores: globalIgnores.ignores
+    },
+    {
+        name: "flat/recommended-with-jsonc - https://github.com/ota-meshi/eslint-plugin-jsonc",
+        extends: jsonc.configs["flat/recommended-with-jsonc"],
+        files: [
+            "*.jsonc",
+            "**/*.jsonc"
+        ],
+        ignores: globalIgnores.ignores
+    },
+    {
+        name: "TSJS",
+        extends: [
+            eslint.configs.recommended as TSESLint.FlatConfig.Config,
+            ...tseslint.configs.strict,
+            ...tseslint.configs.stylistic
+        ],
+        files: [
+            "**/*.ts",
+            "**/*.cts",
+            "**/*.mts",
+            "**/*.js",
+            "**/*.cjs",
+            "**/*.mjs"
+        ],
+        ignores: globalIgnores.ignores,
+        languageOptions: {
+            parserOptions: {
+                project: true,
+                // @ts-expect-error TS2322 Type '{ allowDefaultProjectForFiles: string[]; }' is not assignable to type 'boolean | undefined'.
+                EXPERIMENTAL_useProjectService: {
+                    allowDefaultProjectForFiles: [
+                        "./*.js"
+                    ],
+                    maximumDefaultProjectFileMatchCount_THIS_WILL_SLOW_DOWN_LINTING: 32
+                }
+            },
+            globals: globals.node
+        }
+    },
+    globalIgnores
+);

package/src/findStaticConfig.ts

@@ -0,0 +1,31 @@
+import { existsSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+/// ../static/.releaserc.yml
+export function findStaticConfig(): string {
+	const glob = 'static/.releaserc.yml';
+	let dirPath = fileURLToPath(path.dirname(import.meta.url));
+	let combinedPath = path.join(dirPath, glob);
+
+	while (!existsSync(combinedPath)) {
+		/* file:// + dirname behavior on Windows. 'root' is empty when 'file://' is present.
+		 * file:///C:/Repos
+		 * file:///C:
+		 * file://
+		 * .
+		 */
+		// DEBUG.log(dirPath);
+		// DEBUG.log(combinedPath.href);
+		/** Throw if we reached root. */
+		if (path.dirname(dirPath) === '')
+			throw new Error(
+				`Failed to get full path for HCE.Shared's shared configuration. HCE.Shared recursively searched parent directories for '${glob}' starting from '${path.dirname(
+					import.meta.url,
+				)}'`,
+			);
+		dirPath = path.dirname(dirPath);
+		combinedPath = path.join(dirPath, glob);
+	}
+	return combinedPath;
+}

package/src/index.ts

@@ -1,42 +1,4 @@
-import { existsSync, readFileSync } from "node:fs";
-import path from "node:path";
-import { fileURLToPath } from "node:url";
-import jsYaml from "js-yaml";
-import type { Options } from "semantic-release";
-
-/// ../static/.releaserc.yml
-
-function findStaticConfig(): string {
-  const glob = "static/.releaserc.yml";
-  let dirPath = fileURLToPath(path.dirname(import.meta.url));
-  let combinedPath = path.join(dirPath, glob);
-
-  while (!existsSync(combinedPath)) {
-    /* file:// + dirname behavior on Windows. 'root' is empty when 'file://' is present.
-     * file:///C:/Repos
-     * file:///C:
-     * file://
-     * .
-     */
-    // DEBUG.log(dirPath);
-    // DEBUG.log(combinedPath.href);
-    /** Throw if we reached root. */
-    if (path.dirname(dirPath) === "")
-      throw new Error(
-        `Failed to get full path for HCE.Shared's shared configuration. HCE.Shared recursively searched parent directories for '${glob}' starting from '${path.dirname(
-          import.meta.url,
-        )}'`,
-      );
-    dirPath = path.dirname(dirPath);
-    combinedPath = path.join(dirPath, glob);
-  }
-  return combinedPath;
-}
-
-const options = jsYaml.load(readFileSync(findStaticConfig(), { encoding: "utf8" })) as Options;
-
 /**
  * Runs HCE.Shared and returns a semantic-release "shareable configuration" object.
- * @type {Options}.
- */
-export default options;
+*/
+export { baseConfig as default } from './semanticReleaseConfig.js';

package/src/semantic-release__git.d.ts

@@ -0,0 +1,67 @@
+declare module '@semantic-release/git' {
+	export type MicromatchGlob = string;
+	export interface AssetObject {
+		path: MicromatchGlob;
+	}
+	export type AssetEntry = AssetObject | MicromatchGlob;
+	export interface Options {
+		/**
+		 * Files to include in the release commit. Set to `false` to disable adding files to the release commit.
+		 * @default ['CHANGELOG.md', 'package.json', 'package-lock.json', 'npm-shrinkwrap.json']
+		 * @description
+		 * Can be an Array or a single entry. Each entry can be either:
+		 * - a glob
+		 * - or an Object with a path property containing a glob.
+		 *
+		 * Each entry in the assets Array is globbed individually. A glob can be a String ("dist/\*\*\/\*.js" or "dist/mylib.js") or an Array of Strings that will be globbed together (["dist/\*\*", "!\*\*\/\*.css"]).
+		 *
+		 * If a directory is configured, all the files under this directory and its children will be included.
+		 *
+		 * Note: If a file has a match in assets it will be included even if it also has a match in .gitignore.
+		 *
+		 * @example
+		 * // include all js files in the dist directory, but not in its sub-directories.
+		 * 'dist/*.js'
+		 * // include all js files in the dist directory and its sub-directories.
+		 * 'dist/**\/*.js'
+		 * // include all files in the dist directory and its sub-directories excluding the css files.
+		 * [['dist', '!**\/*.css']]
+		 * // include package.json and all files in the dist directory and its sub-directories excluding the css files.
+		 * [['dist', '!**\/*.css'], 'package.json']
+		 * // include all js and css files in the dist directory and its sub-directories excluding the minified version.
+		 * [['dist/**\/*.{js,css}', '!**\/*.min.*']]
+		 */
+		assets?: AssetEntry | AssetEntry[] | false;
+		/**
+		 * The message for the release commit.
+		 * @default `chore(release): ${nextRelease.version} [skip ci]\n\n${nextRelease.notes}`
+		 * @description
+		 * The message for the release commit is generated with Lodash template. The following variables are available:
+		 * | Parameter         | Description |
+		 * | ----------------- | ----------- |
+		 * | branch            | The branch from which the release is done. |
+		 * | branch.name       | The branch name. |
+		 * | branch.type       | The type of branch. |
+		 * | branch.channel    | The distribution channel on which to publish releases from this branch. |
+		 * | branch.range      | The range of semantic versions to support on this branch. |
+		 * | branch.prerelease | The pre-release detonation to append to semantic versions released from this branch. |
+		 * | lastRelease       | Object with version, gitTag and gitHead of the last release. |
+		 * | nextRelease       | Object with version, gitTag, gitHead and notes of the release being done. |
+		 *
+		 * Note: It is recommended to include `[skip ci]` in the commit message to not trigger a new build. Some CI service support the `[skip ci]` keyword only in the subject of the message.
+		 *
+		 * #### `message` examples
+		 * The `message` `Release <%= nextRelease.version %> - <%= new Date().toLocaleDateString('en-US', {year: 'numeric', month: 'short', day: 'numeric', hour: 'numeric', minute: 'numeric' }) %> [skip ci]\n\n<%= nextRelease.notes %>` will generate the commit message:
+		 * > Release v1.0.0 - Oct. 21, 2015 1:24 AM [skip ci]
+		 * >
+		 * > ## 1.0.0
+		 * >
+		 * > ### Features
+		 * > * Generate 1.21 gigawatts of electricity
+		 * >
+		 * > ...
+		 *
+		 */
+		message?: string;
+	}
+}

package/src/semanticReleaseConfig.ts

@@ -0,0 +1,15 @@
+import { readFileSync } from 'node:fs';
+import jsYaml from 'js-yaml';
+import type { Options, PluginSpec } from 'semantic-release';
+import { findStaticConfig } from './findStaticConfig.js';
+
+export const defaultPlugins = [
+	'@semantic-release/commit-analyzer' as PluginSpec,
+	'@semantic-release/release-notes-generator',
+	'@semantic-release/npm',
+	'@semantic-release/github',
+];
+
+export const baseConfig: Options = jsYaml.load(
+	readFileSync(findStaticConfig(), { encoding: 'utf8' }),
+) as Options;

package/src/semanticReleaseConfigDotnet.ts

@@ -0,0 +1,78 @@
+/** Semantic-Release Config Factory (dotnet)
+ * A functional Semantic-Release configuration for dotnet projects
+ *
+ * extends {@link baseConfig }
+ *
+ * <-- TABLE OF CONTENTS -->
+ * - evaluateProperties
+ * - configureDotnetRelease
+ * - Insert-Edit Plugins
+ * - Append Plugins
+ *
+ */
+
+import { log } from 'node:console';
+import type { Options, PluginSpec } from 'semantic-release';
+import { configureDotnetNugetPush, configurePrepareCmd } from './dotnet/dotnetHelpers.js';
+import { baseConfig, defaultPlugins } from './semanticReleaseConfig.js';
+import { setupGitPluginSpec } from './setupGitPluginSpec.js';
+
+/**
+ * TODO: options/params for inserts/edits. NOT ready for production. Currently, this can only add Git plugin's options if undefined or one or more is missing.
+ * Insert (`array.splice`) and/or configure plugins.\
+ * Can be used to...\
+ * ...load plugin A before plugin B\
+ * ...edit a plugin's existing configuration
+ *
+ * @param config An instance of {@link Options}
+ * @returns a modified copy of {@link config}
+ */
+export function insertAndEditPlugins(config: Options): Options {
+	const newConfig = config;
+	// const insertAndEditCommands = [];
+	newConfig.plugins = [...(config.plugins ?? defaultPlugins)];
+
+	newConfig.plugins = setupGitPluginSpec(newConfig.plugins as PluginSpec[]);
+
+	return newConfig;
+}
+
+export function appendPlugins(
+	config: Options,
+	projectsToPublish: string[],
+	projectsToPackAndPush: string[],
+) {
+	const newConfig = config;
+	if (newConfig.plugins === undefined)
+		throw new Error('Plugins array was undefined when it should be an array!');
+	(newConfig.plugins as PluginSpec[]).push(
+		// APPEND this array of [pluginName, pluginConfig] to plugins
+		// https://github.com/semantic-release/exec#usage
+		[
+			'@semantic-release/exec',
+			{
+				// 'ZipPublishDir' zips each publish folder to ./publish/*.zip
+				prepareCmd: configurePrepareCmd(projectsToPublish, projectsToPackAndPush),
+				publishCmd: configureDotnetNugetPush(),
+			},
+		],
+	);
+	return newConfig;
+}
+
+/**
+ * @type {import("semantic-release").Options}
+ */
+export function getConfig(projectsToPublish: string[], projectsToPackAndPush: string[]) {
+	if (process.argv.includes('--debug') || process.argv.includes('--verbose')) {
+		log(`hce.shared-config:\n${JSON.stringify(baseConfig, null, 2)}`);
+	}
+
+	let newConfig = { ...baseConfig };
+	newConfig = insertAndEditPlugins(newConfig);
+	newConfig = appendPlugins(newConfig, projectsToPublish, projectsToPackAndPush);
+
+	if (process.argv.includes('--debug') || process.argv.includes('--verbose')) {
+		log(`modified plugins array:\n${JSON.stringify(newConfig.plugins, null, 2)}`);
+	}
+}