@powerlines/plugin-nodejs 0.1.0 → 0.1.1

package/dist/plugin-env/src/helpers/reflect.cjs

@@ -0,0 +1,111 @@
+const require_rolldown_runtime = require('../../../_virtual/rolldown_runtime.cjs');
+const require_reflect_type = require('../../../deepkit/src/reflect-type.cjs');
+const require_persistence = require('./persistence.cjs');
+let __stryke_path_is_parent_path = require("@stryke/path/is-parent-path");
+let __stryke_string_format_title_case = require("@stryke/string-format/title-case");
+let __powerlines_deepkit_vendor_type = require("@powerlines/deepkit/vendor/type");
+let __stryke_path_join_paths = require("@stryke/path/join-paths");
+
+//#region ../plugin-env/src/helpers/reflect.ts
+function mergeEnvReflections(context, reflections) {
+	return createEnvReflection(context, { type: (0, __powerlines_deepkit_vendor_type.merge)(reflections.map((reflection) => reflection.type)) });
+}
+function mergeSecretsReflections(context, reflections) {
+	return createSecretsReflection(context, { type: (0, __powerlines_deepkit_vendor_type.merge)(reflections.map((reflection) => reflection.type)) });
+}
+var BaseEnv = class {
+	PLATFORM = "neutral";
+	MODE = "production";
+	DEBUG = false;
+	TEST = false;
+	MINIMAL = false;
+	NO_COLOR = false;
+	FORCE_COLOR = false;
+	FORCE_HYPERLINK = false;
+	STACKTRACE = false;
+	INCLUDE_ERROR_DATA = false;
+	CI = false;
+};
+var BaseSecrets = class {};
+function createEnvReflection(context, options = {}) {
+	const parent = options.superReflection ?? new __powerlines_deepkit_vendor_type.ReflectionClass({
+		kind: __powerlines_deepkit_vendor_type.ReflectionKind.class,
+		description: `The base environment configuration definition for the ${(0, __stryke_string_format_title_case.titleCase)(context.config.name)} project.`,
+		classType: BaseEnv,
+		types: [],
+		implements: [{
+			kind: __powerlines_deepkit_vendor_type.ReflectionKind.objectLiteral,
+			typeName: "EnvInterface",
+			description: `The environment configuration interface definition for the ${(0, __stryke_string_format_title_case.titleCase)(context.config.name)} project.`,
+			types: []
+		}]
+	});
+	parent.name = "Env";
+	const result = new __powerlines_deepkit_vendor_type.ReflectionClass(options.type ?? {
+		kind: __powerlines_deepkit_vendor_type.ReflectionKind.objectLiteral,
+		typeName: "Env",
+		description: `A schema describing the list of available environment variables that can be used by the ${context.config.name ? `${(0, __stryke_string_format_title_case.titleCase)(context.config.name)} application` : "application"}.`,
+		types: []
+	}, parent);
+	result.name = "Env";
+	return result;
+}
+function createSecretsReflection(context, options = {}) {
+	const parent = options.superReflection ?? new __powerlines_deepkit_vendor_type.ReflectionClass({
+		kind: __powerlines_deepkit_vendor_type.ReflectionKind.class,
+		description: `The base secrets configuration definition for the ${(0, __stryke_string_format_title_case.titleCase)(context.config.name)} project.`,
+		classType: BaseSecrets,
+		types: [],
+		implements: [{
+			kind: __powerlines_deepkit_vendor_type.ReflectionKind.objectLiteral,
+			typeName: "SecretsInterface",
+			description: `The secrets configuration interface definition for the ${(0, __stryke_string_format_title_case.titleCase)(context.config.name)} project.`,
+			types: []
+		}]
+	});
+	parent.name = "Secrets";
+	const result = new __powerlines_deepkit_vendor_type.ReflectionClass(options.type ?? {
+		kind: __powerlines_deepkit_vendor_type.ReflectionKind.objectLiteral,
+		typeName: "Secrets",
+		description: `A schema describing the list of available environment secrets that can be used by the ${context.config.name ? `${(0, __stryke_string_format_title_case.titleCase)(context.config.name)} application` : "application"}.`,
+		types: []
+	}, parent);
+	result.name = "Secrets";
+	return result;
+}
+async function reflectEnv(context, file, name) {
+	let config;
+	if (file) config = (0, __powerlines_deepkit_vendor_type.resolveClassType)(await require_reflect_type.reflectType(context, {
+		file: !(0, __stryke_path_is_parent_path.isParentPath)(file, context.workspaceConfig.workspaceRoot) ? (0, __stryke_path_join_paths.joinPaths)(context.workspaceConfig.workspaceRoot, file) : file,
+		name
+	}, { skipNodeModulesBundle: true }));
+	const defaultConfigType = await require_reflect_type.reflectType(context, await require_persistence.getEnvDefaultTypeDefinition(context));
+	return mergeEnvReflections(context, [
+		await require_persistence.readEnvTypeReflection(context, "env"),
+		config,
+		(0, __powerlines_deepkit_vendor_type.resolveClassType)(defaultConfigType)
+	].filter(Boolean));
+}
+async function reflectSecrets(context, file, name) {
+	let config;
+	if (file) config = (0, __powerlines_deepkit_vendor_type.resolveClassType)(await require_reflect_type.reflectType(context, {
+		file: !(0, __stryke_path_is_parent_path.isParentPath)(file, context.workspaceConfig.workspaceRoot) ? (0, __stryke_path_join_paths.joinPaths)(context.workspaceConfig.workspaceRoot, file) : file,
+		name
+	}, { skipNodeModulesBundle: true }));
+	const defaultSecretsType = await require_reflect_type.reflectType(context, await require_persistence.getSecretsDefaultTypeDefinition(context));
+	return mergeSecretsReflections(context, [
+		await require_persistence.readSecretsReflection(context),
+		config,
+		(0, __powerlines_deepkit_vendor_type.resolveClassType)(defaultSecretsType)
+	].filter(Boolean));
+}
+
+//#endregion
+exports.BaseEnv = BaseEnv;
+exports.BaseSecrets = BaseSecrets;
+exports.createEnvReflection = createEnvReflection;
+exports.createSecretsReflection = createSecretsReflection;
+exports.mergeEnvReflections = mergeEnvReflections;
+exports.mergeSecretsReflections = mergeSecretsReflections;
+exports.reflectEnv = reflectEnv;
+exports.reflectSecrets = reflectSecrets;

package/dist/plugin-env/src/helpers/reflect.mjs

@@ -0,0 +1,103 @@
+import { reflectType } from "../../../deepkit/src/reflect-type.mjs";
+import { getEnvDefaultTypeDefinition, getSecretsDefaultTypeDefinition, readEnvTypeReflection, readSecretsReflection } from "./persistence.mjs";
+import { isParentPath } from "@stryke/path/is-parent-path";
+import { titleCase } from "@stryke/string-format/title-case";
+import { ReflectionClass, ReflectionKind, merge, resolveClassType } from "@powerlines/deepkit/vendor/type";
+import { joinPaths } from "@stryke/path/join-paths";
+
+//#region ../plugin-env/src/helpers/reflect.ts
+function mergeEnvReflections(context, reflections) {
+	return createEnvReflection(context, { type: merge(reflections.map((reflection) => reflection.type)) });
+}
+function mergeSecretsReflections(context, reflections) {
+	return createSecretsReflection(context, { type: merge(reflections.map((reflection) => reflection.type)) });
+}
+var BaseEnv = class {
+	PLATFORM = "neutral";
+	MODE = "production";
+	DEBUG = false;
+	TEST = false;
+	MINIMAL = false;
+	NO_COLOR = false;
+	FORCE_COLOR = false;
+	FORCE_HYPERLINK = false;
+	STACKTRACE = false;
+	INCLUDE_ERROR_DATA = false;
+	CI = false;
+};
+var BaseSecrets = class {};
+function createEnvReflection(context, options = {}) {
+	const parent = options.superReflection ?? new ReflectionClass({
+		kind: ReflectionKind.class,
+		description: `The base environment configuration definition for the ${titleCase(context.config.name)} project.`,
+		classType: BaseEnv,
+		types: [],
+		implements: [{
+			kind: ReflectionKind.objectLiteral,
+			typeName: "EnvInterface",
+			description: `The environment configuration interface definition for the ${titleCase(context.config.name)} project.`,
+			types: []
+		}]
+	});
+	parent.name = "Env";
+	const result = new ReflectionClass(options.type ?? {
+		kind: ReflectionKind.objectLiteral,
+		typeName: "Env",
+		description: `A schema describing the list of available environment variables that can be used by the ${context.config.name ? `${titleCase(context.config.name)} application` : "application"}.`,
+		types: []
+	}, parent);
+	result.name = "Env";
+	return result;
+}
+function createSecretsReflection(context, options = {}) {
+	const parent = options.superReflection ?? new ReflectionClass({
+		kind: ReflectionKind.class,
+		description: `The base secrets configuration definition for the ${titleCase(context.config.name)} project.`,
+		classType: BaseSecrets,
+		types: [],
+		implements: [{
+			kind: ReflectionKind.objectLiteral,
+			typeName: "SecretsInterface",
+			description: `The secrets configuration interface definition for the ${titleCase(context.config.name)} project.`,
+			types: []
+		}]
+	});
+	parent.name = "Secrets";
+	const result = new ReflectionClass(options.type ?? {
+		kind: ReflectionKind.objectLiteral,
+		typeName: "Secrets",
+		description: `A schema describing the list of available environment secrets that can be used by the ${context.config.name ? `${titleCase(context.config.name)} application` : "application"}.`,
+		types: []
+	}, parent);
+	result.name = "Secrets";
+	return result;
+}
+async function reflectEnv(context, file, name) {
+	let config;
+	if (file) config = resolveClassType(await reflectType(context, {
+		file: !isParentPath(file, context.workspaceConfig.workspaceRoot) ? joinPaths(context.workspaceConfig.workspaceRoot, file) : file,
+		name
+	}, { skipNodeModulesBundle: true }));
+	const defaultConfigType = await reflectType(context, await getEnvDefaultTypeDefinition(context));
+	return mergeEnvReflections(context, [
+		await readEnvTypeReflection(context, "env"),
+		config,
+		resolveClassType(defaultConfigType)
+	].filter(Boolean));
+}
+async function reflectSecrets(context, file, name) {
+	let config;
+	if (file) config = resolveClassType(await reflectType(context, {
+		file: !isParentPath(file, context.workspaceConfig.workspaceRoot) ? joinPaths(context.workspaceConfig.workspaceRoot, file) : file,
+		name
+	}, { skipNodeModulesBundle: true }));
+	const defaultSecretsType = await reflectType(context, await getSecretsDefaultTypeDefinition(context));
+	return mergeSecretsReflections(context, [
+		await readSecretsReflection(context),
+		config,
+		resolveClassType(defaultSecretsType)
+	].filter(Boolean));
+}
+
+//#endregion
+export { BaseEnv, BaseSecrets, createEnvReflection, createSecretsReflection, mergeEnvReflections, mergeSecretsReflections, reflectEnv, reflectSecrets };

package/dist/plugin-env/src/helpers/source-file-env.cjs

@@ -0,0 +1,24 @@
+const require_rolldown_runtime = require('../../../_virtual/rolldown_runtime.cjs');
+let __stryke_type_checks_is_string = require("@stryke/type-checks/is-string");
+let __stryke_env_types = require("@stryke/env/types");
+let __stryke_string_format_camel_case = require("@stryke/string-format/camel-case");
+
+//#region ../plugin-env/src/helpers/source-file-env.ts
+function removeEnvPrefix(env) {
+	if ((0, __stryke_type_checks_is_string.isString)(env)) {
+		let name = __stryke_env_types.ENV_PREFIXES.reduce((ret, prefix) => {
+			if (ret.startsWith(prefix)) ret = ret.slice(prefix.length);
+			return ret;
+		}, env.toUpperCase());
+		while (name.startsWith("_")) name = name.slice(1);
+		return name;
+	}
+	return Object.keys(env).reduce((ret, key) => {
+		const name = removeEnvPrefix(key);
+		if (name) ret[name] = env[key];
+		return ret;
+	}, {});
+}
+
+//#endregion
+exports.removeEnvPrefix = removeEnvPrefix;

package/dist/plugin-env/src/helpers/source-file-env.mjs

@@ -0,0 +1,23 @@
+import { isString } from "@stryke/type-checks/is-string";
+import { ENV_PREFIXES } from "@stryke/env/types";
+import { camelCase } from "@stryke/string-format/camel-case";
+
+//#region ../plugin-env/src/helpers/source-file-env.ts
+function removeEnvPrefix(env) {
+	if (isString(env)) {
+		let name = ENV_PREFIXES.reduce((ret, prefix) => {
+			if (ret.startsWith(prefix)) ret = ret.slice(prefix.length);
+			return ret;
+		}, env.toUpperCase());
+		while (name.startsWith("_")) name = name.slice(1);
+		return name;
+	}
+	return Object.keys(env).reduce((ret, key) => {
+		const name = removeEnvPrefix(key);
+		if (name) ret[name] = env[key];
+		return ret;
+	}, {});
+}
+
+//#endregion
+export { removeEnvPrefix };

package/dist/plugin-env/src/helpers/template-helpers.cjs

@@ -0,0 +1,2 @@
+require('./persistence.cjs');
+let __stryke_string_format_title_case = require("@stryke/string-format/title-case");

package/dist/plugin-env/src/helpers/template-helpers.mjs

@@ -0,0 +1,4 @@
+import "./persistence.mjs";
+import { titleCase } from "@stryke/string-format/title-case";
+
+export {  };

package/dist/plugin-env/src/index.cjs

@@ -0,0 +1,175 @@
+const require_rolldown_runtime = require('../../_virtual/rolldown_runtime.cjs');
+const require_index = require('../../plugin-babel/src/index.cjs');
+const require_index$1 = require('../../plugin-alloy/src/index.cjs');
+const require_index$2 = require('../../plugin-automd/src/index.cjs');
+const require_reflect = require('./helpers/reflect.cjs');
+const require_persistence = require('./helpers/persistence.cjs');
+const require_plugin = require('./babel/plugin.cjs');
+const require_source_file_env = require('./helpers/source-file-env.cjs');
+const require_load = require('./helpers/load.cjs');
+const require_create_reflection_resource = require('./helpers/create-reflection-resource.cjs');
+const require_env = require('./components/env.cjs');
+const require_automd_generator = require('./helpers/automd-generator.cjs');
+require('./babel/index.cjs');
+require('./components/index.cjs');
+require('./helpers/index.cjs');
+let __alloy_js_core_jsx_runtime = require("@alloy-js/core/jsx-runtime");
+let __storm_software_config_tools_types = require("@storm-software/config-tools/types");
+let __stryke_path_is_parent_path = require("@stryke/path/is-parent-path");
+let defu = require("defu");
+defu = require_rolldown_runtime.__toESM(defu);
+let __stryke_string_format_title_case = require("@stryke/string-format/title-case");
+let __powerlines_deepkit_vendor_type = require("@powerlines/deepkit/vendor/type");
+let __stryke_convert_to_array = require("@stryke/convert/to-array");
+let __stryke_convert_parse_type_definition = require("@stryke/convert/parse-type-definition");
+let __stryke_env_types = require("@stryke/env/types");
+let __stryke_fs_exists = require("@stryke/fs/exists");
+let __stryke_fs_helpers = require("@stryke/fs/helpers");
+let __stryke_path_join = require("@stryke/path/join");
+let __stryke_string_format_constant_case = require("@stryke/string-format/constant-case");
+
+//#region ../plugin-env/src/index.tsx
+/**
+* A Powerlines plugin to inject environment variables into the source code.
+*/
+const plugin = (options = {}) => {
+	return [
+		require_index$1.default(options.alloy),
+		require_index.default(options.babel),
+		{
+			name: "env",
+			async config() {
+				this.log(__storm_software_config_tools_types.LogLevelLabel.TRACE, "Providing default configuration for the Powerlines `env` build plugin.");
+				const config = {
+					env: (0, defu.default)(options, {
+						types: {},
+						prefix: []
+					}),
+					transform: { babel: { plugins: [require_plugin.envBabelPlugin] } }
+				};
+				if (config.env.types) config.env.types = (0, __stryke_convert_parse_type_definition.parseTypeDefinition)(config.env.types);
+				else {
+					this.log(__storm_software_config_tools_types.LogLevelLabel.WARN, "The `env.types` configuration parameter was not provided. Please ensure this is expected.");
+					const envDefaultTypeDefinition = await require_persistence.getEnvDefaultTypeDefinition(this);
+					config.env.types = (0, __stryke_convert_parse_type_definition.parseTypeDefinition)(`${envDefaultTypeDefinition.file}#${envDefaultTypeDefinition.name}`);
+				}
+				if (config.env.secrets) config.env.secrets = (0, __stryke_convert_parse_type_definition.parseTypeDefinition)(config.env.secrets);
+				else {
+					const secretsDefaultTypeDefinition = await require_persistence.getSecretsDefaultTypeDefinition(this);
+					config.env.secrets = (0, __stryke_convert_parse_type_definition.parseTypeDefinition)(`${secretsDefaultTypeDefinition.file}#${secretsDefaultTypeDefinition.name}`);
+				}
+				config.env.prefix = (0, __stryke_convert_to_array.toArray)(config.env.prefix ?? []).reduce((ret, prefix) => {
+					const formattedPrefix = (0, __stryke_string_format_constant_case.constantCase)(prefix);
+					if (!ret.includes(formattedPrefix)) ret.push(formattedPrefix);
+					return ret;
+				}, [...__stryke_env_types.ENV_PREFIXES, "POWERLINES_"]);
+				config.env.prefix = config.env.prefix.reduce((ret, prefix) => {
+					if (!ret.includes(prefix.replace(/_$/g, ""))) ret.push(prefix.replace(/_$/g, ""));
+					return ret;
+				}, []);
+				return config;
+			},
+			async configResolved() {
+				this.log(__storm_software_config_tools_types.LogLevelLabel.TRACE, `Environment plugin configuration has been resolved for the Powerlines project.`);
+				this.config.env.inject ??= this.config.projectType === "application";
+				this.env = (0, defu.default)({ parsed: await require_load.loadEnv(this, this.config.env) }, this.env ?? {}, {
+					types: { env: {} },
+					used: {
+						env: {},
+						secrets: {}
+					},
+					parsed: {},
+					injected: {}
+				});
+				if (this.config.command !== "prepare" && this.persistedMeta?.checksum === this.meta.checksum && (0, __stryke_fs_exists.existsSync)(require_persistence.getEnvTypeReflectionsPath(this, "env"))) {
+					this.log(__storm_software_config_tools_types.LogLevelLabel.TRACE, `Skipping reflection initialization as the meta checksum has not changed.`);
+					this.env.types.env = await require_persistence.readEnvTypeReflection(this, "env");
+					if ((0, __stryke_fs_exists.existsSync)(require_persistence.getEnvReflectionsPath(this, "env"))) this.env.used.env = await require_persistence.readEnvReflection(this);
+					if ((0, __stryke_fs_exists.existsSync)(require_persistence.getEnvTypeReflectionsPath(this, "secrets"))) this.env.types.secrets = await require_persistence.readEnvTypeReflection(this, "secrets");
+					if ((0, __stryke_fs_exists.existsSync)(require_persistence.getEnvReflectionsPath(this, "secrets"))) this.env.used.secrets = await require_persistence.readSecretsReflection(this);
+				} else {
+					this.env.types.env = await require_reflect.reflectEnv(this, this.config.env.types?.file ? (0, __stryke_path_is_parent_path.isParentPath)(this.config.env.types?.file, this.workspaceConfig.workspaceRoot) ? this.config.env.types?.file : (0, __stryke_path_join.joinPaths)(this.config.projectRoot, this.config.env.types?.file) : void 0, this.config.env.types?.name);
+					if (!this.env.types.env) throw new Error("Failed to find the environment configuration type reflection in the context.");
+					await require_persistence.writeEnvTypeReflection(this, this.env.types.env, "env");
+					this.env.types.secrets = await require_reflect.reflectSecrets(this, this.config.env.secrets?.file ? (0, __stryke_path_is_parent_path.isParentPath)(this.config.env.secrets?.file, this.workspaceConfig.workspaceRoot) ? this.config.env.secrets?.file : (0, __stryke_path_join.joinPaths)(this.config.projectRoot, this.config.env.secrets?.file) : void 0, this.config.env.secrets?.name);
+					if (!this.env.types.secrets) throw new Error("Failed to find the secrets configuration type reflection in the context.");
+					await require_persistence.writeEnvTypeReflection(this, this.env.types.secrets, "secrets");
+					this.log(__storm_software_config_tools_types.LogLevelLabel.TRACE, `Resolved ${this.env.types.env.getProperties().length ?? 0} environment configuration parameters and ${this.env.types.secrets?.getProperties().length ?? 0} secret configuration parameters`);
+					const envWithAlias = this.env.types.env.getProperties().filter((prop) => prop.getAlias().length > 0);
+					Object.entries(await require_load.loadEnv(this, this.config.env)).forEach(([key, value]) => {
+						const unprefixedKey = this.config.env.prefix.reduce((ret, prefix) => {
+							if (key.replace(/_$/g, "").startsWith(prefix)) return key.replace(/_$/g, "").slice(prefix.length);
+							return ret;
+						}, key);
+						const aliasKey = envWithAlias.find((prop) => prop?.getAlias().reverse().includes(unprefixedKey));
+						if (this.env.types.env?.hasProperty(unprefixedKey) || aliasKey) this.env.types.env.getProperty(unprefixedKey).setDefaultValue(value);
+					});
+					this.env.used.env = new __powerlines_deepkit_vendor_type.ReflectionClass({
+						kind: __powerlines_deepkit_vendor_type.ReflectionKind.objectLiteral,
+						typeName: "Env",
+						description: `An object containing the environment configuration parameters used by the ${this.config.name ? `${this.config.name} application` : "application"}.`,
+						types: []
+					}, this.env.types.env);
+					await require_persistence.writeEnvReflection(this, this.env.used.env, "env");
+					if (this.env.types.secrets) {
+						await require_persistence.writeEnvTypeReflection(this, this.env.types.secrets, "secrets");
+						this.env.used.secrets = new __powerlines_deepkit_vendor_type.ReflectionClass({
+							kind: __powerlines_deepkit_vendor_type.ReflectionKind.objectLiteral,
+							typeName: "Secrets",
+							description: `An object containing the secret configuration parameters used by the ${this.config.name ? `${this.config.name} application` : "application"}.`,
+							types: []
+						}, this.env.types.secrets);
+						await require_persistence.writeEnvReflection(this, this.env.used.secrets, "secrets");
+					}
+				}
+			},
+			async prepare() {
+				const _self$ = this;
+				this.log(__storm_software_config_tools_types.LogLevelLabel.TRACE, `Preparing the Environment runtime artifacts for the Powerlines project.`);
+				return this.render((0, __alloy_js_core_jsx_runtime.createComponent)(require_env.EnvBuiltin, { get defaultConfig() {
+					return _self$.config.env.defaultConfig;
+				} }));
+			},
+			async docs() {
+				this.log(__storm_software_config_tools_types.LogLevelLabel.TRACE, "Writing Environment documentation for the Powerlines project artifacts.");
+				const outputPath = (0, __stryke_path_join.joinPaths)(this.config.projectRoot, "docs", "generated");
+				if (!(0, __stryke_fs_exists.existsSync)(outputPath)) await (0, __stryke_fs_helpers.createDirectory)(outputPath);
+				const reflection = await require_persistence.readEnvTypeReflection(this, "env");
+				const envDocFile = (0, __stryke_path_join.joinPaths)(outputPath, "env.md");
+				this.log(__storm_software_config_tools_types.LogLevelLabel.TRACE, `Documenting environment variables configuration in "${envDocFile}"`);
+				await this.fs.write(envDocFile, `<!-- Generated by ${(0, __stryke_string_format_title_case.titleCase)(this.config.framework) || "Powerlines"} -->
+
+Below is a list of environment variables used by the [${this.packageJson.name}](https://www.npmjs.com/package/${this.packageJson.name}) package. These values can be updated in the \`.env\` file in the root of the project. The variables in the list below are used as configuration parameters to drive the processing of the application. The data contained in these variables are **not** considered sensitive or confidential. Any values provided in these variables will be available in plain text to the public.
+
+| Name | Description | Type | Default Value | Required |
+| ---- | ----------- | ---- | ------------- | :------: |
+${reflection.getProperties().filter((property) => property.getNameAsString() !== "__POWERLINES_INJECTED__").sort((a, b) => a.getNameAsString().localeCompare(b.getNameAsString())).map((reflectionProperty) => {
+					return `| ${reflectionProperty.getNameAsString().trim()} | ${(reflectionProperty.getDescription()?.replaceAll("\r", "")?.replaceAll("\n", "") ?? "").trim()} | ${(0, __powerlines_deepkit_vendor_type.stringifyType)(reflectionProperty.getType()).trim().replaceAll(" | ", ", or ")} | ${reflectionProperty.hasDefault() ? String(reflectionProperty.getDefaultValue())?.includes("\"") ? reflectionProperty.getDefaultValue() : `\`${reflectionProperty.getDefaultValue()}\`` : ""} | ${reflectionProperty.isValueRequired() ? "" : "✔"} |`;
+				}).join("\n")}
+`);
+			},
+			async buildEnd() {
+				const reflectionPath = require_persistence.getEnvReflectionsPath(this, "env");
+				this.log(__storm_software_config_tools_types.LogLevelLabel.TRACE, `Writing env reflection types to ${reflectionPath}.`);
+				await require_persistence.writeEnvReflection(this, this.env.used.env, "env");
+			}
+		},
+		{
+			name: "env:automd-generator",
+			config() {
+				return { automd: (0, defu.default)(options.automd ?? {}, { generators: { "env": require_automd_generator.env(this) } }) };
+			}
+		},
+		{
+			name: "env:vite",
+			vite: { configResolved() {
+				return { envPrefix: this.config?.env?.prefix };
+			} }
+		},
+		require_index$2.default(options.automd)
+	];
+};
+var src_default$3 = plugin;
+
+//#endregion
+exports.default = src_default$3;

package/dist/plugin-env/src/index.mjs

@@ -0,0 +1,173 @@
+import src_default$2 from "../../plugin-babel/src/index.mjs";
+import src_default from "../../plugin-alloy/src/index.mjs";
+import src_default$1 from "../../plugin-automd/src/index.mjs";
+import { BaseEnv, BaseSecrets, createEnvReflection, createSecretsReflection, mergeEnvReflections, mergeSecretsReflections, reflectEnv, reflectSecrets } from "./helpers/reflect.mjs";
+import { getEnvDefaultTypeDefinition, getEnvReflectionsPath, getEnvTypeReflectionsPath, getSecretsDefaultTypeDefinition, readEnvReflection, readEnvTypeReflection, readSecretsReflection, resolveRuntimeTypeFile, writeEnvReflection, writeEnvTypeReflection } from "./helpers/persistence.mjs";
+import { envBabelPlugin } from "./babel/plugin.mjs";
+import { removeEnvPrefix } from "./helpers/source-file-env.mjs";
+import { loadEnv, loadEnvFromContext } from "./helpers/load.mjs";
+import { createReflectionResource } from "./helpers/create-reflection-resource.mjs";
+import { EnvBuiltin, EnvTypeDefinition } from "./components/env.mjs";
+import { env } from "./helpers/automd-generator.mjs";
+import "./babel/index.mjs";
+import "./components/index.mjs";
+import "./helpers/index.mjs";
+import { createComponent } from "@alloy-js/core/jsx-runtime";
+import { LogLevelLabel } from "@storm-software/config-tools/types";
+import { isParentPath } from "@stryke/path/is-parent-path";
+import defu from "defu";
+import { titleCase } from "@stryke/string-format/title-case";
+import { ReflectionClass, ReflectionKind, stringifyType } from "@powerlines/deepkit/vendor/type";
+import { toArray } from "@stryke/convert/to-array";
+import { parseTypeDefinition } from "@stryke/convert/parse-type-definition";
+import { ENV_PREFIXES } from "@stryke/env/types";
+import { existsSync } from "@stryke/fs/exists";
+import { createDirectory } from "@stryke/fs/helpers";
+import { joinPaths } from "@stryke/path/join";
+import { constantCase } from "@stryke/string-format/constant-case";
+
+//#region ../plugin-env/src/index.tsx
+/**
+* A Powerlines plugin to inject environment variables into the source code.
+*/
+const plugin = (options = {}) => {
+	return [
+		src_default(options.alloy),
+		src_default$2(options.babel),
+		{
+			name: "env",
+			async config() {
+				this.log(LogLevelLabel.TRACE, "Providing default configuration for the Powerlines `env` build plugin.");
+				const config = {
+					env: defu(options, {
+						types: {},
+						prefix: []
+					}),
+					transform: { babel: { plugins: [envBabelPlugin] } }
+				};
+				if (config.env.types) config.env.types = parseTypeDefinition(config.env.types);
+				else {
+					this.log(LogLevelLabel.WARN, "The `env.types` configuration parameter was not provided. Please ensure this is expected.");
+					const envDefaultTypeDefinition = await getEnvDefaultTypeDefinition(this);
+					config.env.types = parseTypeDefinition(`${envDefaultTypeDefinition.file}#${envDefaultTypeDefinition.name}`);
+				}
+				if (config.env.secrets) config.env.secrets = parseTypeDefinition(config.env.secrets);
+				else {
+					const secretsDefaultTypeDefinition = await getSecretsDefaultTypeDefinition(this);
+					config.env.secrets = parseTypeDefinition(`${secretsDefaultTypeDefinition.file}#${secretsDefaultTypeDefinition.name}`);
+				}
+				config.env.prefix = toArray(config.env.prefix ?? []).reduce((ret, prefix) => {
+					const formattedPrefix = constantCase(prefix);
+					if (!ret.includes(formattedPrefix)) ret.push(formattedPrefix);
+					return ret;
+				}, [...ENV_PREFIXES, "POWERLINES_"]);
+				config.env.prefix = config.env.prefix.reduce((ret, prefix) => {
+					if (!ret.includes(prefix.replace(/_$/g, ""))) ret.push(prefix.replace(/_$/g, ""));
+					return ret;
+				}, []);
+				return config;
+			},
+			async configResolved() {
+				this.log(LogLevelLabel.TRACE, `Environment plugin configuration has been resolved for the Powerlines project.`);
+				this.config.env.inject ??= this.config.projectType === "application";
+				this.env = defu({ parsed: await loadEnv(this, this.config.env) }, this.env ?? {}, {
+					types: { env: {} },
+					used: {
+						env: {},
+						secrets: {}
+					},
+					parsed: {},
+					injected: {}
+				});
+				if (this.config.command !== "prepare" && this.persistedMeta?.checksum === this.meta.checksum && existsSync(getEnvTypeReflectionsPath(this, "env"))) {
+					this.log(LogLevelLabel.TRACE, `Skipping reflection initialization as the meta checksum has not changed.`);
+					this.env.types.env = await readEnvTypeReflection(this, "env");
+					if (existsSync(getEnvReflectionsPath(this, "env"))) this.env.used.env = await readEnvReflection(this);
+					if (existsSync(getEnvTypeReflectionsPath(this, "secrets"))) this.env.types.secrets = await readEnvTypeReflection(this, "secrets");
+					if (existsSync(getEnvReflectionsPath(this, "secrets"))) this.env.used.secrets = await readSecretsReflection(this);
+				} else {
+					this.env.types.env = await reflectEnv(this, this.config.env.types?.file ? isParentPath(this.config.env.types?.file, this.workspaceConfig.workspaceRoot) ? this.config.env.types?.file : joinPaths(this.config.projectRoot, this.config.env.types?.file) : void 0, this.config.env.types?.name);
+					if (!this.env.types.env) throw new Error("Failed to find the environment configuration type reflection in the context.");
+					await writeEnvTypeReflection(this, this.env.types.env, "env");
+					this.env.types.secrets = await reflectSecrets(this, this.config.env.secrets?.file ? isParentPath(this.config.env.secrets?.file, this.workspaceConfig.workspaceRoot) ? this.config.env.secrets?.file : joinPaths(this.config.projectRoot, this.config.env.secrets?.file) : void 0, this.config.env.secrets?.name);
+					if (!this.env.types.secrets) throw new Error("Failed to find the secrets configuration type reflection in the context.");
+					await writeEnvTypeReflection(this, this.env.types.secrets, "secrets");
+					this.log(LogLevelLabel.TRACE, `Resolved ${this.env.types.env.getProperties().length ?? 0} environment configuration parameters and ${this.env.types.secrets?.getProperties().length ?? 0} secret configuration parameters`);
+					const envWithAlias = this.env.types.env.getProperties().filter((prop) => prop.getAlias().length > 0);
+					Object.entries(await loadEnv(this, this.config.env)).forEach(([key, value]) => {
+						const unprefixedKey = this.config.env.prefix.reduce((ret, prefix) => {
+							if (key.replace(/_$/g, "").startsWith(prefix)) return key.replace(/_$/g, "").slice(prefix.length);
+							return ret;
+						}, key);
+						const aliasKey = envWithAlias.find((prop) => prop?.getAlias().reverse().includes(unprefixedKey));
+						if (this.env.types.env?.hasProperty(unprefixedKey) || aliasKey) this.env.types.env.getProperty(unprefixedKey).setDefaultValue(value);
+					});
+					this.env.used.env = new ReflectionClass({
+						kind: ReflectionKind.objectLiteral,
+						typeName: "Env",
+						description: `An object containing the environment configuration parameters used by the ${this.config.name ? `${this.config.name} application` : "application"}.`,
+						types: []
+					}, this.env.types.env);
+					await writeEnvReflection(this, this.env.used.env, "env");
+					if (this.env.types.secrets) {
+						await writeEnvTypeReflection(this, this.env.types.secrets, "secrets");
+						this.env.used.secrets = new ReflectionClass({
+							kind: ReflectionKind.objectLiteral,
+							typeName: "Secrets",
+							description: `An object containing the secret configuration parameters used by the ${this.config.name ? `${this.config.name} application` : "application"}.`,
+							types: []
+						}, this.env.types.secrets);
+						await writeEnvReflection(this, this.env.used.secrets, "secrets");
+					}
+				}
+			},
+			async prepare() {
+				const _self$ = this;
+				this.log(LogLevelLabel.TRACE, `Preparing the Environment runtime artifacts for the Powerlines project.`);
+				return this.render(createComponent(EnvBuiltin, { get defaultConfig() {
+					return _self$.config.env.defaultConfig;
+				} }));
+			},
+			async docs() {
+				this.log(LogLevelLabel.TRACE, "Writing Environment documentation for the Powerlines project artifacts.");
+				const outputPath = joinPaths(this.config.projectRoot, "docs", "generated");
+				if (!existsSync(outputPath)) await createDirectory(outputPath);
+				const reflection = await readEnvTypeReflection(this, "env");
+				const envDocFile = joinPaths(outputPath, "env.md");
+				this.log(LogLevelLabel.TRACE, `Documenting environment variables configuration in "${envDocFile}"`);
+				await this.fs.write(envDocFile, `<!-- Generated by ${titleCase(this.config.framework) || "Powerlines"} -->
+
+Below is a list of environment variables used by the [${this.packageJson.name}](https://www.npmjs.com/package/${this.packageJson.name}) package. These values can be updated in the \`.env\` file in the root of the project. The variables in the list below are used as configuration parameters to drive the processing of the application. The data contained in these variables are **not** considered sensitive or confidential. Any values provided in these variables will be available in plain text to the public.
+
+| Name | Description | Type | Default Value | Required |
+| ---- | ----------- | ---- | ------------- | :------: |
+${reflection.getProperties().filter((property) => property.getNameAsString() !== "__POWERLINES_INJECTED__").sort((a, b) => a.getNameAsString().localeCompare(b.getNameAsString())).map((reflectionProperty) => {
+					return `| ${reflectionProperty.getNameAsString().trim()} | ${(reflectionProperty.getDescription()?.replaceAll("\r", "")?.replaceAll("\n", "") ?? "").trim()} | ${stringifyType(reflectionProperty.getType()).trim().replaceAll(" | ", ", or ")} | ${reflectionProperty.hasDefault() ? String(reflectionProperty.getDefaultValue())?.includes("\"") ? reflectionProperty.getDefaultValue() : `\`${reflectionProperty.getDefaultValue()}\`` : ""} | ${reflectionProperty.isValueRequired() ? "" : "✔"} |`;
+				}).join("\n")}
+`);
+			},
+			async buildEnd() {
+				const reflectionPath = getEnvReflectionsPath(this, "env");
+				this.log(LogLevelLabel.TRACE, `Writing env reflection types to ${reflectionPath}.`);
+				await writeEnvReflection(this, this.env.used.env, "env");
+			}
+		},
+		{
+			name: "env:automd-generator",
+			config() {
+				return { automd: defu(options.automd ?? {}, { generators: { "env": env(this) } }) };
+			}
+		},
+		{
+			name: "env:vite",
+			vite: { configResolved() {
+				return { envPrefix: this.config?.env?.prefix };
+			} }
+		},
+		src_default$1(options.automd)
+	];
+};
+var src_default$3 = plugin;
+
+//#endregion
+export { src_default$3 as default };